README
¶
IED App Engine Data Access
ieddata is part of the "Edgeshark" project that consist of several
repositories:
- Edgeshark Hub repository
- G(h)ostwire discovery service
- Packetflix packet streaming service
- Containershark Extcap plugin for Wireshark
- support modules:
- csharg (CLI)
- mobydig
- 🖝 ieddata 🖜
Installation
go get github.com/siemens/ieddata@latest
Note: ieddata supports versions of Go 1 that are noted by the Go release
policy, that is, major
versions N and N-1 (where N is the current major version).
Usage
This example queries a Siemens Industrial Edge (virtual) device's...
- ...device name and its owner,
- ...and the list of installed applications.
Error handling has been left out for brevity.
db, _ := ieddata.Open("platformbox.db")
defer db.Close()
di, _ := db.DeviceInfo()
fmt.Printf("device name: %s\nowner name: %s\n", di["deviceName"], di["ownerName"])
apps, _ := db.Apps()
slices.SortFunc(apps, func(a, b ieddata.App) bool { return a.Title < b.Title })
for _, app := range apps {
fmt.Printf("app: %q %s\n", app.Title, app.Id)
}
Nota bene: the IED's
platformbox.dbis opened always in read-only mode. Thus, the underlying database connection on purpose does not allow callers to modify the IED's databases using this module.
View Package Documentation Locally
make pkgsite
Then navigate to http://localhost:6060/github.com/siemens/ieddata.
Deployment
Please note that an application using this Go module needs to have capability
CAP_SYS_PTRACE requested in its composer file, as well as your binary needs to
be executed with CAP_SYS_PTRACE also effective, not just permitted. If you
run your binary under a non-UID0 user, then you need to assign file capabilities
to your binary (see also
setcap(8)).
Additionally, you need to deploy any container that leverages this Go module
with pid:host in order to access the file system view (mount namespaces) of
other containers.
Unit Tests
This Go module comes with unit tests and some of these unit tests need to be run as root (UID 0). The unit tests additionally require an operational Docker container engine to be up and running (for simulating a fake IED edge core runtime container). To run the tests, simply do:
make test
The unit tests also include checks for file descriptor leaks.
Contributing
Please see CONTRIBUTING.md.
License and Copyright
(c) Siemens AG 2023
Documentation
¶
Overview ¶
Package ieddata returns IED-related information to an IE app on the IED. This information comes from the app engine databases used and maintained by the IED runtime container (“edge-iot-core”).
Example (ListInstalledApps) ¶
List the Industrial Edge Apps installed on this IED, with their titles and app IDs.
package main
import (
"fmt"
"golang.org/x/exp/slices"
ieddata "github.com/siemens/ieddata"
)
func main() {
db, err := ieddata.Open("platformbox.db")
if err != nil {
panic(err)
}
defer db.Close()
apps, err := db.Apps()
if err != nil {
panic(err)
}
// Sort the apps by their titles in order to get a stable output result that
// can also be tested.
slices.SortFunc(apps, func(a, b ieddata.App) bool { return a.Title < b.Title })
for _, app := range apps {
fmt.Printf("%q %s %s\n", app.Title, app.Version, app.Id)
}
}
Output: "AppA" 1.9.18 195ff5e2e15a149ca5eb7c59d3857cc5 "AppB" 0.6.66666666666 7bd06d3bbf816d0658d5a871b0a498ff "AppC" 1.1.0 1842f53281412f9c657c7765494ff80e "AppD" 0.19.1 2a267358a0403fddb039924fbc4f3169
Example (ShowDeviceInfo) ¶
Shows some of the IED key-values, such as the device name and owner name.
package main
import (
"fmt"
"github.com/siemens/ieddata"
)
func main() {
db, err := ieddata.Open("platformbox.db")
if err != nil {
panic(err)
}
defer db.Close()
di, err := db.DeviceInfo()
if err != nil {
panic(err)
}
fmt.Printf("device name: %s\nowner name: %s\n", di["deviceName"], di["ownerName"])
}
Output: device name: iedx12345 owner name: The Doctor
Index ¶
Examples ¶
Constants ¶
const EdgeIotCoreContainerName = "edge-iot-core"
EdgeIotCoreContainerName is the name of the IED runtime container.
const PlatformBoxDb = "platformbox.db"
PlatformBoxDb is the file name of the platform box database.
Variables ¶
This section is empty.
Functions ¶
func FirstLower ¶
FirstLower returns a copy of the specified string with only its first character in lower case.
Types ¶
type App ¶
type App struct {
Id string `db:"appId"`
Version string `db:"appVersion"`
VersionId string `db:"appVersionId"` // semantic version string
VersionStatus int
ReleaseNotes string
OwnerId string `db:"appOwnerId"`
UserId string
ProjectId string
Title string
RepositoryName string
Description string
URL string `db:"webAddress"`
IconPath string `db:"icon"`
AppStatus int
CompanyName string
CompanyURL string `db:"companyWebAddress"`
IsDeveloperAppInstall int
IsVisible int
SortWeight int
RunAsService bool `db:"runasservice"`
IsUpdatedOnPortal int
Created time.Time `db:"createdDate"`
Modified time.Time `db:"modifiedDate"`
ComposerFilepath string `db:"composerFilePath"`
RedirectType string
RedirectUrl string
RESTRedirectUrl string `db:"restRedirectUrl"`
RedirectSection string
ToExecuteOrder string
Metadata string
ServiceLabels string
IsSecure int
IsSwarmModeEnable int
IsDebuggingEnabled int `db:"isDebuggingEnabled"`
}
App describes an individual installed IE app, including version information. This is basically a “JOIN” of the “application” and “applicationversions” tables, using the appId column, of the platformbox.db.
Field names almost always match their corresponding table column names, but with an initial uppercase letter necessary due to Go's implicit export rules. The few exceptions are URL and CompanyURL instead of Company/(w)ebAddress, Created/Modified instead of (c)reated/ModifiedDate, as well as avoiding stuttering as to not use “App” prefixes.
type AppEngineDB ¶
AppEngineDB implements access to an IED app engine host database.
func Open ¶
func Open(dbname string) (*AppEngineDB, error)
Open returns a new database “connection” to the specified app engine DB (in read-only mode), such as “platformboxdb”, or an error, if neither the IED runtime container nor its app engine database(s) could be located.
The database name is sanitizied by keeping only alpha-numerically (ASCII) characters, as well as dots “.” (but not “..”), dashes “-”, and underscores “_”.
Open hides the details of discovering the IED runtime container in a way that then gives direct file system access to the app engine DBs inside this container.
func OpenInPID ¶
func OpenInPID(dbname string, pid model.PIDType) (*AppEngineDB, error)
OpenInPID works like Open, but additionally requires the PID of the container with the app engine DB(s) to be explicitly specified. Use OpenInPID when the IED's runtime container PID is already known, such as from an lxkns discovery, as so to skip the IE runtime container discovery.
func (*AppEngineDB) Apps ¶
func (db *AppEngineDB) Apps() ([]App, error)
Apps returns a slice of App elements with information about the currently installed apps and their versions. The information is read from the application and applicationversions tables in a “platformbox.db”, so make sure that the correct database has been Open'ed.
func (*AppEngineDB) Close ¶
func (db *AppEngineDB) Close() error
Close closes the database connection and ensures to additionally dispose of the helper resources required to read from an SQLite database in another container.
func (*AppEngineDB) DeviceInfo ¶
func (db *AppEngineDB) DeviceInfo() (map[string]string, error)
DeviceInfo returns the key-value pairs describing an IED as per the device table in a platformbox.db.
Source Files