Command Line Interface

pyobs comes with two different command line tools, pyobs and pyobsd, which can run a single module or start multiple ones, respectively.

Default parameters via config file

Instead of passing parameters on the command line every time, both pyobs and pyobsd can read their default values from a YAML config file. The first of the following locations that exists is used:

~/.config/pyobs.yaml
/etc/pyobs.yaml
/opt/pyobs/storage/pyobs.yaml

Within that file, parameters go into a section named after the tool, e.g.:

pyobs:
  log_level: debug

pyobsd:
  path: /opt/pyobs
  chuid: pyobs:pyobs

Only a fixed set of parameters can be set this way (roughly those without a value that changes between runs, such as the module config file itself). Command line parameters always take precedence over values from the config file. Which config file was picked, if any, is logged on startup.

Module launcher pyobs

The pyobs command runs a single module. A typical command for running pyobs simply defines a configuration file:

pyobs config.yaml

Parameters

The command accepts the following optional parameters:

-h/–help:: Shows the help for the pyobs command.
–log-level <level>:: One of critical, error, warning, info, debug. Indicates the level of logging.
-l/–log-file <file>:: If provided, in addition to logging to stdout, the log is also written to the given file.
–log-rotate:: Only valid in combination with -l/–log-file. Requests an automated rotation of log files to avoid large files.
–syslog:: If given, log messages are also sent to the systemd journal, tagged with the module name.
-p/–pid-file <file>:: If given, pyobs writes its process ID into the given file and starts in the background.
–gui:: Shows an additional GUI, which is especially useful under Windows, where a graceful exit is otherwise impossible.
–username <username> and –password <password>:: Username and password for connecting to the central server can be provided here as well as in the given config or in environment variables.
–server <host:ip>:: If the server to connect to cannot be inferred from the username, another one can be specified as <host>:<ip>.
–comm <type>:: The Comm type to use, if –username and –password are provided on command line. Must be xmpp at the moment.

Username and password

There are three different ways for providing a server connection:

Provide it in the config YAML file. It then should have a section like this:

comm:
  class: pyobs.comm.xmpp.XmppComm
  jid: test@example.com
  password: topsecret

Use the –username and –password command line parameters.
Provide the username and password in the environment variables PYOBS_USERNAME and PYOBS_PASSWORD, respectively. The server can be defined via PYOBS_SERVER.

pyobsd daemon

The pyobsd command can automatically start and stop multiple modules, if their configuration files are all stored in a single directory.

Commands

There are four basic commands:

pyobsd start:: A call to pyobsd start starts modules from every single configuration YAML file it can find. Every additional parameter limits this to the given module, i.e. pyobsd start camera only starts the camera module with aconfiguration in camera.yaml.
pyobsd stop:: Works the same way as pyobsd start, but stops the modules.
pyobsd restart:: The restart command is equivalent to calling first stop and then start
pyobsd status:: Gives an overview of detected configuration files and started modules.

CLI Parameters

The command accepts the following optional parameters:

-h/–help:: Shows the help for the pyobs command.
-c/–config-path <path>:: Defines the path in which to look for configuration files, defaults to /opt/pyobs/config.
-r/–run-path <path>:: Defines the path in which to store PID files, defaults to /opt/pyobs/run.
-r/–run-path <path>:: Defines the path in which to store log files, defaults to /opt/pyobs/log.
–log-level <level>:: One of critical, error, warning, info, debug. Indicates the level of logging.
–syslog:: If given, forwards –syslog to every started module, so their log messages are also sent to the systemd journal.
–chuid <user>:<group>:: Switches user to the given user in the given group when starting/stopping a module, defaults to pyobs.
–start-stop-daemon <path>:: The path to the start-stop-daemon executable, defaults to /sbin/start-stop-daemon.

Note that none of the pathes have to be defined, if the recommended path structure is used.