Documentation/sysconfig

System configuration file

The kinguard system components store all generic none security sensitive configuration in a central configuration file "/etc/kinguard/sysconfig.json".

This file should however never be manually edited it should always be accessed programatically using either libkgp or any wrapper to this library described further down.

File Syntax

For reference here is the layout of the sysconfig json file. Please read the file for reference but never ever edit it manually.

The complete configuration file is one json object (note that javascript object syntax is not permitted).

The file is set up using a "scope" and "key/value" pairs.

All scope and key identifiers shall be lowercase and written with letters and digits only, no "-" or "_".

Example:

{
  "webapps":
  {
    "theme":"kgp"
  },
  "hostinfo":
  {
    "unitid":"c79f425c-9af7-4f38-b1ba-d53277b14939",
    "hostname":"myhost",
    "domain":"example.org"
  },
  "dns":
  {
    "availabledomains":["op-i.me","mykeep.net"]
  }
}

Native access via libkgp

Libkgp is the main library to use when programming locally for the kinguard system it contains c++ objects for managing all kinguard functions. No official documentation exists for this yet but pointers on how it works can be found in the unit tests and in the applications utilizing them for example KGP backend and KGP startup control

To access the system configuration the SysConfig class

Wrappers

Most wrappers can also be used to access other information provided by libkgp, such as the current running system type, information about system storage etc.

Shell Scripts

For shell scripts, use "kgp-sysinfo". Run kgp-sysinfo --help for options.

Example:

# kgp-sysinfo -c hostinfo -k unitid -p
c79f425c-9af7-4f38-b1ba-d53277b14939

# kgp-sysinfo -c hostinfo -k unitid
{"unitid":"c79f425c-9af7-4f38-b1ba-d53277b14939"}

Python

For Python3, use the python library "pylibopi"

Example:

>>> import pylibopi
>>> pylibopi.StorageDevice()
'/dev/disk/by-path/platform-f10a8000.sata-ata-2'

C

For C programs, libkgp_wrapper can be used.

PHP

Currently no native PHP wrapper exists, but kgp-sysinfo defaults to output json (see above) that can easily be used in PHP.

Config scopes and variables

Very few of these parameters are mandatory. However default behavior for the applications will vary if an expected parameter is missing.

- autoupdate
     |- enabled     turns on and off automatic updates

- backup
     |- backend           which storage backend to use for s3ql 
     |- devicemountpath   where to mount local devices, such as usb memories
     |- enabled           turns on and off the backup service

- dns
     |- dnsauthkey    path to the private key used for lower level authentication on service provider backends
     |- dnspubkey     path to corresponding public key
     |- enabled       turns on and off dns updates
     |- provider      backend provider

- filesystem
     |- storagemount  mountpoint of storage volume
     |- luksdevice    luks-created cryptodevice (If used)
     |- lvmdevice     lvm-created storage pool (If used)
     |- lvmvg         lvm-created volume group (If used)
     |- lvmlv         lvm-created logical volume (If used)

- hostinfo
     |- unitid        system id to use as account identifier for service provider backends
     |- hostname      the 'host' part of the FQDN
     |- domain        the 'domain' part of the FQDN
     |- cafile        the ca file used to verify service provider backends
     |- sysauthkey    the key used to access data on service provider backends
     |- syspubkey     corresponding public key

- mail
     |- localmail    configuration file for local mail delivery, relative to filesystem->storagemount
     |- virtualalias configuration file for virtual mail aliases, relative to filesystem->storagemount
     |- vmailbox     path to virtual mailbox mapping, relative to filesystem->storagemount
     |- vdomains     path to virtual domains file (Which domains to accept mail from), relative to filesystem->storagemount
     |- saslpasswd   path to sasl password store file, relative to filesystem->storagemount
     |- oprelayserver URL to OpenProducts smtp-relay

- setup
     |- conntesthost  host used for connectivity tests

- upnp
     |- forwardports  which ports the device shall try to forward from a UPNP gateway
 
- webapps
     |- theme         the theme used by webapps

- webcertificate
     |- backend       backend provider
     |- enabled       turns on and off generation of web certificates
     |- certpath      the location where signed certificate are stored
     |- customcert    full path to custom certificate
     |- customkey     full path to private key for the custom certificate
     |- defaultcert   full path to default (fallback) certificate
     |- defaultkey    full path to private key for the default (fallback) certificate
     |- activecert    path to symlink for the certificate being used
     |- activekey     path to symlink for key corresponding to activecert