osctl and osctld are general purpose tools meant for system administrators. They're not the tools that can be given to end users to manage their containers. osctld is designed in a way to make integration with information systems with custom business logic as easy as possible.
To simplify parsing, osctl has global option
--parsable, which is used
to get exact data, i.e. not formatted in a human readable form. Global option
--json formats output in JSON.
Useful list options:
-Hdo not show header
-o fields...select what fields to print
-Lprint available fields
osctl also includes a Ruby client library OsCtl::Client. You can use this class to connect to osctld and issue commands.
osctl interacts with osctld using a local socket at
/run/osctl/osctld.sock. The protocol is described in documentation of
OsCtld::Generic::ClientHandler. In short, the protocol is line-based, data
formatted in JSON. Client sends a command with parameters, osctld executes it
and reports success or failure.
For the list of commands, see osctld sources. This interface may change
between versions, you're encouraged to use
One of the management commands is
event_subscribe. Subscribed clients are
informed abour various events, such as management commands,
adding/removing/changing of users, groups and containers.
osctl -j monitor
will print all events in JSON to standard output.