# Feature Internals

## systemd

Cockpit uses systemd and the DBus APIs it provides to configure and monitor core aspects of the system. Use of alternate system APIs are not currently implemented.

For non root users, systemd controls access to its APIs via Policy Kit and a user logged into Cockpit will have the same permissions as they do from the command line.

Cockpit retrieves information about the host and changes the hostname via the `hostnamed` daemon. To perform similar tasks from the command line use the `hostnamectl` command:

    $ hostnamectl
       Static hostname: pink.example.com
       Pretty hostname: Pink
             Icon name: computer-desktop
               Chassis: desktop
            Machine ID: ef00b79be229463cbb844c3e715de96c
               Boot ID: 934983d64d34465cb5a8383b5a89ad8c
      Operating System: Fedora 22 (Twenty Two)
           CPE OS Name: cpe:/o:fedoraproject:fedora:22
                Kernel: Linux 4.0.4-301.fc22.x86_64
          Architecture: x86-64

Cockpit configures the system time and time zone via the `timedated` daemon. To perform similar tasks from the command line use the `timedatectl` command:

    $ timedatectl list-timezones
    Africa/Abidjan
    Africa/Accra
    Africa/Addis_Ababa
    Africa/Algiers
    ...

Cockpit can manage the list of NTP servers used by `systemd-timesyncd` by putting its own file into `/etc/systemd/timesyncd.conf.d/`. Note that `systemd-timesyncd` is not always enabled, depending on the configuration of the machine. In that case, Cockpit disabled the UI for managing the list of NTP servers. In some cases use of `ntpd` can cause the `timedated` daemon to behave inconsistently with regards to time synchronization.

Cockpit reboots or powers down the machine by using the `shutdown` command. To perform similar tasks from the command line, run it directly:

    $ sudo shutdown +15
    Shutdown scheduled for Sa 2015-09-26 15:49:40 CEST, use 'shutdown -c' to cancel.

Cockpit manages system services and sockets via systemd. To perform similar tasks from the command line use the `systemctl` command:

    $ systemctl status cockpit
    ● cockpit.service - Cockpit Web Service
       Loaded: loaded (/usr/lib/systemd/system/cockpit.service; static; vendor preset: disabled)
      Drop-In: /etc/systemd/system/cockpit.service.d
               └─debug.conf
       Active: active (running) since Sa 2015-09-26 13:28:02 CEST; 2h 7min ago
         Docs: man:cockpit-ws(8)
     Main PID: 6957 (cockpit-ws)
       Memory: 1.8M
       CGroup: /system.slice/cockpit.service
               ├─ 6957 /usr/libexec/cockpit-ws
               └─29598 /usr/bin/ssh-agent

In order to customize who can perform various actions in system, create polkit rules with the following actions and details:

`org.freedesktop.systemd1.manage-units`

  Permission to manage system services or other units. Details available: `unit`, `verb`

`org.freedesktop.systemd1.manage-unit-files`

  Permission to manage system services or other unit files.

`org.freedesktop.systemd1.reload-daemon`

  Permission to reload the systemd state.

For example, placing the following polkit rule to `/etc/polkit-1/rules.d/10-http.rule` allows all users in the `operators` group start, stop, and restart the Apache HTTP service:

    polkit.addRule(function(action, subject) {
        if (action.id == "org.freedesktop.systemd1.manage-units") {
            if (subject.isInGroup("operators") && action.lookup("unit") == "httpd.service") {
                var verb = action.lookup("verb");
                if (verb == "start" || verb == "stop" || verb == "restart") {
                    return polkit.Result.YES;
                }
            }
        }
    });

## Journal

The systemd journal provides Cockpit with indexed log data. This log data is found on the Journal page, as well as in various other places when configuring services, storage, networking etc.

Cockpit accesses Journal data via the `journalctl` command. Similar tasks can be performed at the command line:

    $ sudo journalctl -f -u docker
    ...

## NetworkManager

If available on the system, Cockpit uses NetworkManager and the DBus APIs it provides to interact with the system’s network configuration.

For non root users, NetworkManager controls access to its APIs via Policy Kit and a user logged into Cockpit will have the same permissions as they do from the command line.

To perform similar tasks from the command line, use the nmcli command:

    $ nmcli general status
    STATE      CONNECTIVITY  WIFI-HW  WIFI     WWAN-HW  WWAN
    connected  full          enabled  enabled  enabled  enabled

Devices marked as "not managed" with the `NM_CONTROLLED=no` setting will not be displayed in the interface.

## Firewall

Cockpit uses firewalld to interact with the system’s firewall. No firewall configuration UI will be shown if firewalld is not installed.

Firewalld controls access to its APIs via PolicyKit. The user logged into Cockpit needs to have the appropriate permissions to view or modify the settings.

Cockpit can currently only show, add, and remove predefined firewalld services in the default zone.

To perform similar tasks from the command line, use firewall-cmd. For example, to get the same list of allowed services that Cockpit displays:

    $ sudo firewall-cmd --list-services
    dhcpv6-client samba-client mdns ssh cockpit

To enable an additional service, use:

    $ firewall-cmd --add-service pop3
    success

## storaged

If available on the system, Cockpit uses `storaged` to configure and monitor storage, disks, mounts etc. on the system. This functionality is present in the Cockpit storaged package.

The `storaged` project is originally based on a project called `udisks` and added support for many more features such as LVM, iSCSI, Multipath, and BTRFS. The same tools and backwards compatible API are available between `storaged` and `udisks` the projects. Cockpit can use `udisks` but disables many of it’s storage related features, including updating `/etc/fstab` and `/etc/crypttab` for stability reasons.

For non root users, storaged controls access to its APIs via Policy Kit and a user logged into Cockpit will have the same permissions as they do from the command line.

To perform similar tasks from the command line, use the `storagedctl` command:

    $ udisksctl dump
    ...

To perform LVM tasks, you may use the various LVM commands, such as `vgcreate`, `lvresize` and so on. Cockpit will detect such changes made at the command line.

Cockpit recognizes devices with multiple paths and can start the `multipathd` service in case it is not running. On the command line, you can control multipath features with the `mpathconf`, `multipathd`, and `multipath` commands.

To manage iSCSI initiators from the command line, you can use `iscsiadm` and related tools.

## User Tools

Cockpit uses the usual tools to create and modify local user accounts. Examples are `useradd`, `usermod` and `passwd`. These same tools are available for use on the command line.

## realmd

If available on the system, Cockpit uses realmd and the DBus APIs it provides to configure the system’s Active Directory or IPA domain membership.

Not all systems can join all kinds of domains. This depends on the availability of the necessary client software.

For non root users, realmd controls access to its APIs via Policy Kit and a user logged into Cockpit will have the same permissions as they do from the command line.

To perform similar tasks from the command line, use the realm command:

    $ realm join example.com
    Password for Administrator:

realmd sets up domain-qualified user names by default, i. e. login user names look like “user@example.com”. For using unqualified names (just “user”), set the `fully-qualified-names` option in /etc/realmd.conf before joining a domain.

Cockpit requests an SSL certificate from the IPA server for `cockpit-ws` with the ipa-getcert command.

## Terminal

Cockpit provides a standard shell in a terminal. This shell and the processes running in it have the same privileges as if the user had logged in via SSH.

## PCP Metrics

If available, Cockpit uses the Performance Co-Pilot framework to gather metrics data about the system. This data is used to display the history graphs on the "Metrics and history" page. Cockpit can use the PCP logging feature to display archived data about the system from a different point in time. If PCP is not available, then Cockpit gathers the metrics data itself, but archival features are not available.

Whether or not metrics are archived depends on whether the `pmlogger.service` systemd unit is running or not. The "Enable PCP metrics collector" button on the Metrics page will enable and start this service.

To see similar metrics data from the command line, you can use tools like `pmstat` or `pminfo`:

    $ pmstat
    @ Sat Sep 26 15:30:10 2015
     loadavg                      memory      swap        io    system         cpu
       1 min   swpd   free   buff  cache   pi   po   bi   bo   in   cs  us  sy  id
        4.19      0 20710m 605148  6450m    0    0    0 2548 5688  14K  19   3  76
    ...

These metrics can also be exposed to other machines on a TCP port with pmproxy and Redis or Valkey:

    systemctl enable --now redis pmproxy
    # if you use firewalld, open port 44322:
    firewall-cmd --permanent --add-service pmproxy
    firewall-cmd --reload

This allows you to gather and visualize PCP metrics from multiple machines with Grafana and the PCP Grafana plugin.

## Multiple Machines

Warning | This feature is deprecated as of Cockpit 322.

Cockpit can connect to multiple machines from a single Cockpit session. These are listed in the host switcher.

These additional machines are accessed via SSH from the machine that the first machine connected to, and are authenticated with the logged in user’s password and/or SSH keys.

SSH host keys are stored in `/etc/ssh/ssh_known_hosts`.

The machine data is stored in `/etc/cockpit/machines.d/*.json`, or below `$XDG_CONFIG_DIRS` if set (see cockpit.conf). Settings in lexicographically later files amend or override settings in earlier ones. Cockpit itself writes into `99-webui.json`; packages or admins who want to pre-configure machines should ship files like `05-mymachine.json` so that changes from the web interface override the pre-configured files.

Each JSON file contains an object that maps machine IDs to objects that define the properties of that machine. The ID can be a human readable name or an IP address or any other unique value, and is shown in the web interface until connecting to it the first time, at which point the web interface will show the machine’s host name.

The following properties are recognized:

`"address"`

  (string, mandatory) IP address or DNS name of the machine

`"visible"`

  (boolean, optional) If `true`, the machine will be displayed and available for managing with Cockpit. If `false` (the default), it will not be displayed, but still taken into account for type-ahead search when adding new machines in the web interface.

`"user"`

  (string, optional) User name on the remote machine. When not given, Cockpit will default to the user name that was being used to log into Cockpit itself.

`"port"`

  (integer, optional) ssh port of the remote machine. When not given, the default port 22 is used.

`"color"`

  (string, optional) Color to assign to the machine label in the web interface. This can be either given as `rgb(r_value, g_value, b_value)` with each value being an integer between 0 and 255, or as a color name like `yellow`. When not given, Cockpit will assign an unused color automatically.

Example:

    {
        "web server": {
            "address": "192.168.2.4",
            "visible": true,
            "color": "rgb(100, 200, 0)",
            "user": "admin"
        },
        "192.168.2.1": {
            "address": "192.168.2.1",
            "port": 2222,
            "visible": true,
            "color": "green"
        }
    }

## SELinux Policy

If present on the system Cockpit can set the SELinux mode to enforcing or permissive. It can also use `setroubleshootd` to show audit issues and apply suggested fixes.

To perform similar tasks from the command line use the `setenforce` and `sealert` tools.

To clear out all the information that `setroubleshootd` tracks, you can use a commands like:

    $ sudo killall setroubleshootd
    $ sudo rm -rf /var/lib/setroubleshoot/*

## Tuned Profiles

If present on the system Cockpit can use Tuned and the DBUS API it provides to set system performance profiles. To perform similar tasks from the command line, use the `tuned-adm` command.

## SOS Report

If present on the system Cockpit can use `sosreport` to collect system configuration and diagnostic information.

To perform similar tasks from the command line, use the `sosreport` command.

## Package Updates

Cockpit uses the PackageKit D-Bus API to get information about available package updates and to apply them, in an Operating System independent manner.

To perform similar tasks from the command line, use the pkcon command:

    $ pkcon refresh

    $ pkcon get-updates
    Available  sudo-1.8.20p2-1.fc26.x86_64 (updates-testing)
        Allows restricted root access for specified users
    Available  vim-filesystem-2:8.0.617-1.fc26.x86_64 (updates-testing)
        VIM filesystem layout
    Available  vim-minimal-2:8.0.617-1.fc26.x86_64 (updates-testing)
        A minimal version of the VIM editor

    $ pkcon get-update-detail sudo
    Details about the update:6.x86_64 [fedora]
     Package: sudo-1.8.20p2-1.fc26.x86_64
     Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1452941
     Update text: - update to 1.8.20p2
        - added sudo package to dnf/yum protected packages

    $ pkcon update
    The following packages have to be updated:
     sudo-1.8.20p2-1.fc26.x86_64    Allows restricted root access for specified users
     vim-filesystem-2:8.0.617-1.fc26.x86_64 VIM filesystem layout
     vim-minimal-2:8.0.617-1.fc26.x86_64    A minimal version of the VIM editor
    Proceed with changes? [N/y] y
    [...]

Of course you can also use your Operating System specific commands for that, such as `dnf updateinfo info` on Fedora or `sudo apt upgrade` on Debian.