README
¶
IED App Engine Data Access
iedata provides querying information about a Siemens Industrial Edge (virtual)
device from an app inside the IE(v)D.
[!NOTE]
This package is "CGO-free" as it leverages the modernc.org/sqlite sqlite3 driver module. When using the
ieddatamodule, please make sure that your main module'sgo.mod(indirectly) requires themodernc/libcmodule in the same version as required bymodernc.org/sqlite'sgo.mod.
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:
- turtlefinder
- csharg (CLI)
- mobydig
- 🖝 ieddata 🖜
Usage
The following 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) int { return strings.Compare(a.Title, b.Title) })
for _, app := range apps {
fmt.Printf("app: %q %s\n", app.Title, app.Id)
}
Nota bene: we first copy the IED's
platformbox.dbin a temporary location and the open only the copy.
DevContainer
[!CAUTION]
Do not use VSCode's "
Dev Containers: Clone Repository in Container Volume" command, as it is utterly broken by design, ignoring.devcontainer/devcontainer.json.
git clone https://github.com/siemens/ieddata- in VSCode: Ctrl+Shift+P, "Dev Containers: Open Workspace in Container..."
- select
ieddata.code-workspaceand off you go...
Supported Go Versions
morbyd supports versions of Go that are noted by the Go release
policy, that is, major
versions N and N-1 (where N is the current major version).
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.
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"
"slices"
"strings"
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) int { return strings.Compare(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 `db:"userId"`
ProjectId string `db:"projectId"`
Title string `db:"title"`
RepositoryName string `db:"repositoryName"`
Description string `db:"description"`
URL string `db:"webAddress"`
IconPath string `db:"icon"`
AppStatus int
CompanyName string `db:"companyName"`
CompanyURL string `db:"companyWebAddress"`
IsDeveloperAppInstall int `db:"isDeveloperAppInstall"`
IsVisible int `db:"isVisible"`
SortWeight int `db:"sortWeight"`
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, 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