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.
Arigi is distributed as a generic .tar.gz file containing the arigisrv binary and supporting scripts and documentation.
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
ARIGI_ prefix. For example, the option
be set by the environment variable
ARIGI_LISTEN_ADDRESS. For boolean
flags, use the environment values
The following general options are available:
Interval between device status checks. Accepts a number with a unit prefix (
Maximum number of parallell HTTPS requests that may be outstanding at any given moment (default:
Do not push configuration to devices
Do not use standard global discovery servers over IPv4
Do not use standard global discovery servers over IPv6
Use custom discovery server (can be given multiple times)
The external, visible URL to Arigi (default
Directory for persistent data (default
Address to listen on (default
Disable HTTPS (see Authentication & HTTPS)
1.0, 1.1, or 1.2 (default
SMTP options (see Configuring SMTP):
SMTP server address
SMTP auth user
SMTP auth password
SMTP from address
Automatic enrollment options (see Automatic Enrollment):
Address to listen on for enrollment server
Enrollment server default API key
Enrollment server default API port (default
Enrollment server tags for new devices (option can be repeated)
LDAP authentication options (see LDAP Authentication):
Address to an LDAP server, host:port (option can be repeated)
Bind userID or DN
Search base DN
Use LDAPS for the connection
Use StartTLS for the connection
Backup and restore:
Create backup of the database
Restore backup of the database
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.
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.
The default credentials on initial login are user ID
admin and password
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.
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:389for standard LDAP, or
dc1.example.com:636for LDAPS. This option can be repeated to enable multiple servers for failover.
--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
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.
--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:
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:
In this setup we will use the following options:
--ldap-server dc1.kastelo.net:389 --ldap-bind-user email@example.com --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:
When this filter is used, the placeholder
%s is replaced by the user
name entered in the login form. The two terms
(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
For the following group:
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:
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:
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.)