Formal paper for AsiaBSDCon 2017.

1. FreeBSD System Administration Using SysAdm
Dru Lavigne
dru@freebsd.org
Abstract
System administrators rely on a variety of built-in and third-party utilities to manage their FreeBSD
systems. Management becomes more complex as the number of systems to administer increases,
requiring the administrator to manage multiple connections and authorization keys. Third-party
management utilities may rely on a configuration database which does not integrate manual edits to
existing configuration files. Most third-party utilities require learning a new scripting language and
do not provide hooks for ZFS management or FreeBSD-specific utilities such as jails. Further, the
FreeBSD Project does not provide a REST API for management of remote systems.
SysAdm is a framework for administering a local or any number of remote FreeBSD or TrueOS
systems. It is designed to complement FreeBSD's built-in configuration files, provides graphical
and scriptable methods for performing routine system administration tasks, and includes a
notification system to alert the administrator of events that require attention.
The SysAdm framework is built into TrueOS and is available as a FreeBSD package. In addition,
the graphical component is cross-platform and also available for the Windows and Mac OS X
operating systems.
Introduction
The SysAdm framework is comprised of three components:
1. Server: a daemon that listens for local or remote connection requests. The server can listen
for both single-request and established connections and uses a well-defined and documented
API of classes to manage authentication, event notifications, and common system
administration tasks.
2. Client: a graphical front-end for connecting to and interacting with the server.
3. Bridge: a relay for managing connections to servers with dynamic IP addresses or through a
firewall. This component is still experimental and under testing.
This paper provides an overview of each component's features and usage. It then provides pointers
to additional resources.

2. SysAdm Server
The SysAdm Server provides the middleware to facilitate interactions between the user and the
managed system. The Server must be installed and running on the system to be managed. The
Server supports the JSON text format over two connection types:
• REST: single-request connection that requires user and password authentication with every
request.
• WebSockets: long-lived connection that provides pure JSON input and output. It uses one-
time authentication with a configurable timeout or disconnect for inactivity. This type of
connection can also be used to define events that result in system notifications or status
updates.
Both types of connections can run simultaneously, on different sockets, to allow for multiple access
methods. The Server requires TLS encryption over HTTPS or WSS. It also requires authentication,
which can be either a username and password or an SSL public/private key pair. The administrator
has the option to disable password authentication and to require key authentication. The server
enforces configurable connection timeouts and blacklisting and provides privilege separation
through the wheel and operator groups. Instead of relying on a configuration database, all system
information and configuration changes are performed directly to the built-in configuration files
using either the SysAdm Client or a SysAdm API request.
The SysAdm API provides a set of classes for managing various aspects of the system. Table 1 lists
the available classes and provides a short description for each.
Table 1: SysAdm API Classes
Class Used to View and Manage
beadm ZFS boot environments
dispatcher External processes such as scripts
firewall IPFW
fs Files and directories
iocage Jails
iohyve Bhyve
lifepreserver ZFS snapshots and replication
logs System logs
pkg Packages
services Services
systemmanager Memory, CPU, processes, battery information, mounts, sysctls, system
shutdown
update System updates
zfs ZFS pools and datasets

3. Each API class provides a list of actions which can be used to either view or change the current
state of a configurable element. When using the API directly, the administrator can choose to send a
request using a one-time (REST) or a long-lived (WebSockets) connection. Example 1 demonstrates
the requests and response for listing ZFS boot environments using the beadm class and the listbes
action. Example 2 demonstrates how to use the beadm class and the createbe action to create the
specified boot environment.
Example 1: Listing Boot Environments
REST Request
PUT /sysadm/beadm
{
"action" : "listbes"
}
WebSockets Request
{
"name" : "beadm",
"namespace" : "sysadm",
"id" : "fooid",
"args" : {
"action" : "listbes"
}
}
Server Response
{
"args": {
"listbes": {
"11.0-CURRENTJAN2016-up-20160128_150853": {
"active": "NR",
"date": "2016-01-28",
"mount": "/",
"nick": "14:57",
"space": "10.2G"
},
"initial": {
"active": "-",
"date": "2016-01-28",
"mount": "-",
"nick": "07:00",
"space": "1.2G"
}
}
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}

4. Example 2: Creating a New Boot Environment
REST Request
PUT /sysadm/beadm
{
"action" : "createbe",
"newbe" : "red",
"clonefrom" : "green"
}
WebSockets Request
{
"id" : "fooid",
"args" : {
"newbe" : "red",
"clonefrom" : "green",
"action" : "createbe"
},
"namespace" : "sysadm",
"name" : "beadm"
}
Server Response
{
"args": {
"createbe": {
"clonefrom": "green",
"newbe": "red"
}
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
The SysAdm API Reference Guide1
describes the actions for each available class and provides
usage examples for each action.
SysAdm Client
The SysAdm Client is a suite of graphical utilities which provide a front-end to the SysAdm API's
classes and actions. The utilities are written with Qt5 in order to maximize cross-platform support.
At this time, the TrueOS Project has automated builds for the FreeBSD, Windows, and OS X
versions of the SysAdm Client.
1 http://api.sysadm.us/

5. The SysAdm Client can be used to manage the local or multiple remote systems. For security
reasons, access to remote systems is disabled by default so that the administrator can configure
secure connections to those systems. The SysAdm Client integrates into the system tray in order to
provide notifications of events. Example notifications include available security or software updates
and notification of a completed ZFS replication task.
Connections to remote systems occur over a secure Websockets connection. A valid username and
password is required for the first connection at which time a unique SSL key pair is created,
registered, and required for subsequent connections. Registered certificates and keys are stored on
the client system within an encrypted file that is protected by a user-defined password. Encrypted
client settings can be imported and exported, allowing the administrator to manage remote systems
from multiple client devices. A graphical Connection Manager utility is provided for generating
keys and managing connections.
The Client utilities are listed in a graphical Control Panel. The list of available utilities may vary,
depending upon what is installed on the client system. For example, the iohyve utility will not
appear in the Control Panel if iohyve is not installed on the system. An example of a Control Panel
listing on a TrueOS system can be seen in Figure 1.
Figure 1: Example Control Panel

6. Figure 2 shows an example of the AppCafe utility, a graphical front-end to pkg.
Figure 2: AppCafe Utility
Figure 3 shows an example of the Task manager utility, a graphical front-end to top.
Figure 3: Task Manager Utility

7. Table 2 summarizes the utilities that are available at this time. More utilities will be added as
additional API classes are created.
Table 2: SysAdm Client Utilities
Utility Used to Manage
AppCafe Packages
Update Manager System and package updates
Connection Manager SSL certificates and SysAdm connections
Boot Environment Manager ZFS boot environments
Firewall Manager IPFW firewall
Service Manager System services
Task Manager View memory and CPU usage and kill running
processes
User Manager Local users and groups
Life Preserver ZFS replication tasks and snapshots
iohyve VM Manager bhyve instances
System Manager System information
SysAdm Bridge
The SysAdm Bridge is an optional component that can be configured to manage connections to
systems with dynamic addresses or which reside behind a firewall. The bridge itself requires a
static, public IP address but can be hosted elsewhere, such as on a cloud-based virtual machine. By
design, the bridge is considered to be a completely untrusted relay. This means that servers and
clients use a separate SSL certificate when talking to the bridge to ensure that their real certificate is
never used to connect to an unknown system.
Once connected to the bridge, the server or client sends the MD5 of their real SSL certificate. The
bridge responds with the ID and location of any systems which list that MD5 in their configured
certificate list.

8. Summary
SysAdm is specifically designed for the secure administration of FreeBSD systems. By providing a
suite of graphical utilities as well a scriptable API, SysAdm gives system administrators another set
of tools for managing their local and remote FreeBSD systems.
Additional Resources
Server Repository: https://github.com/trueos/sysadm/
Client Repository: https://github.com/trueos/sysadm-ui-qt
Documentation Repository: https://github.com/trueos/sysadm-docs
SysAdm API Reference Guide: http://api.sysadm.us/
SysAdm Client Guide: http://sysadm.us/handbook/client/
SysAdm Server Guide: http://sysadm.us/handbook/server/