Installation

Requirements

Please ensure the following requirements prior to commencing installation.

  • A Unixy server. Arigi runs fine on Debian, Ubuntu, CentOS and RedHat Enterprise Linux. It probably runs fine on most other flavors of Linux too. FreeBSD, macOS (“Darwin”) and Solaris are also good choices. The server should have Internet access. The exact resource requirements are dependent on the number of devices and their configuration; however, a baseline of 1 GiB of RAM and one CPU core is sufficient in most cases. A virtual machine is fine.

  • One or more Syncthing devices to manage. Syncthing version 0.14 and above are supported.

Procedure

Arigi is distributed as a generic .tar.gz file containing the arigisrv binary and supporting scripts and documentation.

Configuration

While all day to day configuration (managed devices, etc.) is done through the Arigi GUI, some server wide settings must be provided at started.

All options can be set as flags or environment variables. The environment variable corresponding to each flag is named in upper case, with underscores and the ARIGI_ prefix. For example, the option --listen-address can be set by the environment variable ARIGI_LISTEN_ADDRESS. For boolean flags, use the environment values true or false.

The following general options are available:

--check-interval

Interval between device status checks. Accepts a number with a unit prefix (h, m, or s) (default: 5m)

--concurrency

Maximum number of parallell HTTPS requests that may be outstanding at any given moment (default: 100)

--disable-configurator

Do not push configuration to devices

--disable-v4-disco

Do not use standard global discovery servers over IPv4

--disable-v6-disco

Do not use standard global discovery servers over IPv6

--custom-disco=URL

Use custom discovery server (can be given multiple times)

--server--external-url

The external, visible URL to Arigi (default https://localhost:2525)

--home

Directory for persistent data (default /opt/var/arigi)

--listen-address

Address to listen on (default :2525)

--listen-insecure

Disable HTTPS (see Authentication & HTTPS)

--listen-min-tls-version

1.0, 1.1, or 1.2 (default 1.2)

SMTP options (see Configuring SMTP):

--smtp-server

SMTP server address

--smtp-user

SMTP auth user

--smtp-password

SMTP auth password

--smtp-from

SMTP from address

ElasticSearch options:

--elastic-url

ElasticSearch URL

Automatic enrollment options (see Automatic Enrollment):

--enrollment-address

Address to listen on for enrollment server

--enrollment-api-key

Enrollment server default API key

--enrollment-api-port

Enrollment server default API port (default 8384)

--enrollment-tag

Enrollment server tags for new devices (option can be repeated)

LDAP authentication options (see LDAP Authentication):

--ldap-server

Address to an LDAP server, host:port (option can be repeated)

--ldap-bind-user

Bind userID or DN

--ldap-bind-password

Bind password

--ldap-search-base

Search base DN

--ldap-search-pattern

Search pattern, %s placeholder (default (|(sAMAccountName=%s)(mail=%s)))

--ldap-use-ldaps

Use LDAPS for the connection

--ldap-use-starttls

Use StartTLS for the connection

Backup and restore:

--backup-to

Create backup of the database

--restore-from

Restore backup of the database

Installing

Untar the distribution into a suitable directory. Our recommended default is /opt, resulting in the default Arigi installation directory /opt/arigi.

# mkdir -p /opt # cd /opt
# tar zxvf ~/arigi-linux-amd64-v1.0.tar.gz

You also need a directory for persistent data. The recommended location is the default, /opt/var/arigi. Make sure this directory is owned by the non-root user that will be running Arigi.

# mkdir -p /opt/var/arigi
# chown arigi:arigi /opt/var/arigi

Any other existing, local user can be used instead of arigi:arigi. Edit the default variables in /opt/arigi/bin/start.sh to set the directory paths in use and the database parameters. To run Arigi you use the start.sh script. It is highly recommended to run Arigi as a separate, non-root user.

# su - arigi
$ /opt/arigi/bin/start.sh

In summary, you should now have the following files and directories in place:

  • /opt/etc/arigi/: Directory for read-only configuration.

  • /opt/arigi/: Directory for the distribution.

  • /opt/arigi/bin/: Directory for executable files.

  • /opt/arigi/bin/arigi: A CLI interface to Arigi.

  • /opt/arigi/bin/arigisrv: The main Arigi binary.

  • /opt/arigi/bin/start.sh: The startup helper script.

  • /opt/var/arigi/: Directory for read-write data.

Running

Use your favorite operating system method to keep Arigi running. Possibilities include systemd, runit, daemon-tools, and cron. The arigi binary, and hence the start.sh script, will not exit unless Arigi encounters a fatal error.

Authentication & HTTPS

Arigi by default uses HTTPS and creates a certificate pair on startup if one is missing. It is recommended that this certificate either be replaced with a CA issued certificate, or added to the local trust store.

It is also possible to run Arigi in HTTP only mode behind a secure reverse proxy, such as Nginx, Apache or Caddy.

Please note that the arigi command line tool requires that a trusted certificate is used, whether CA issued or by local trust policy. As an alternative, plain HTTP can be used with the --listen-insecure flag to arigisrv and the --api-insecure flag to arigi.

Note

The default credentials on initial login are user ID admin and password arigi.

Docker Image

For quick deployment and testing there is a Docker image available.

# docker run -d --name arigi --restart=always \
    -p 2525:2525 kastelo/arigi

Give the container a few seconds to start, and then visit http://localhost:2525/ (or the address of the host running the container if not localhost). Data in the container is stored in /opt/var/arigi. You can bind a volume in order to get persistent storage independent of the container.

Arigi will generate and use a self signed key pair if one is not already present on the volume.

Configuring SMTP

TBD

LDAP Authentication

Arigi can be configured to delegate authentication to an external LDAP source. Typical examples include Microsoft Active Directory and OpenLDAP / OpenDirectory servers. When LDAP authentication is configured the user cannot change their password, email or display name through Arigi. Instead these changes should be done in the LDAP / Active Directory system directly.

To enable LDAP authentication, the following must be set:

  • --ldap-server: Set to the address of the LDAP server, with hostname and port. For example, dc1.example.com:389 for standard LDAP, or dc1.example.com:636 for LDAPS. This option can be repeated to enable multiple servers for failover.

  • --ldap-bind-user and --ldap-bind-password: Set to the user and password for performing directory searches. The user name should be in the format accepted by the LDAP server, typically as a full DN (OpenLDAP) or user@domain (AD).

  • --ldap-search-base: Set to the base DN under which users are found in the directory. Typically, for an AD domain “example.com”, something like CN=Users,DC=example,DC=com.

To use TLS for connection security, set either --ldap-use-ldaps (server port should be 636) or --ldap-use-starttls (server port should be 389). In either case the server needs a correct, valid certificate matching the given server hostname.

The --ldap-search-pattern option is an LDAP search filter to match on the user ID entered by the user in the login form. The default is suitable for AD and matches on either account name or email address.

Active Directory Example Configuration

Consider the following typical AD setup:

../../_images/ldap1.png

We have a domain called ad.kastelo.net and a user called “Arigi Bind” that we will use for searches. In the user account details we can see the logon name that we will use:

../../_images/ldap2.png

In this setup we will use the following options:

--ldap-server dc1.kastelo.net:389
--ldap-bind-user arigi@ad.kastelo.net
--ldap-bind-password ...
--ldap-search-base CN=Users,DC=ad,DC=kastelo,DC=net

The other options are acceptable at their defaults. Users will be able to use their logon name (sAMAccountName) or email to log in.

Enforcing Group Memberhip

In some cases it may be desirable to restrict login to members of a certain group. We do this by using a custom search filter that matches users who belong to the group only.

The default search filter is:

(|(sAMAccountName=%s)(mail=%s))

When this filter is used, the placeholder %s is replaced by the user name entered in the login form. The two terms (sAMAccountName=...) and (mail=...) then search for users with a matching logon name or email address. The outer vertical pipe (|...) is LDAP syntax for “or”, meaning we accept matches on either logon name or email address. In order to modify this to match only users belonging to a group, we must first find the group DN.

For the following group:

../../_images/ldap3.png

We can deduce the DN by the domain name and “Users” container to be CN=Arigi Users,CN=Users,DC=ad,DC=kastelo,DC=net. We can also use the command line tool dsquery to find the same information:

../../_images/ldap4.png

Whichever method we use, we can now add it to the search filter. We need to take the existing, default, search filter and combine it with a memberOf search on the group name using an “and” criteria. By itself, that looks like:

(&(memberOf=CN=Arigi Users,CN=Users,DC=ad,DC=kastelo,DC=net)...)

where the “…” part is the original search pattern. The total search query option that we use then becomes:

--ldap-search-pattern
  "(&(memberOf=CN=Arigi Users,CN=Users,DC=ad,DC=kastelo,DC=net)
  (|(sAMAccountName=%s)(mail=%s)))"

(Line breaks for clarity only.)