UniFi Controller: Difference between revisions

From Alpine Linux
No edit summary
m (This article has got to go.)
 
(24 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{Draft}}
{{TOC right}}
 
{{Delete|Due to the warning below ⬇️, the unavailability of the image file for the controller (link below has been dead for ages), and Alpine Linux 3.9 being support level "none", there's no reason to keep this article any longer.}}
 
{{Warning|The Ubiquiti Unifi controller Linux self-contained Java image relies on MongoDB, and MongoDB has been removed from Alpine Linux after version 3.9 due to SPL license changes, so this guide doesn't work.}}
 
== Introduction ==
 
This guide explains how to install the generic Unix UniFi Controller, as available from [https://www.ui.com/ Ubiquiti Networks]. At the time of writing this, a native Alpine Linux package is not available.
 
Furthermore, this guide uses the incredibly reliable and efficient [https://www.skarnet.org/software/s6/ s6] supervision suite to start and control the UniFi Controller.
 
A summarized schematic of what will be installed on the filesystem.
 
The choice of {{path|/srv}} for the UniFi Controller's root directory is based on the fact that it contains both run-time and configuration data, so installing to {{path|/usr/local}}, {{path|/opt}} or {{path|/home}} didn't seem appropriate. Feel free to adjust the steps below, replacing {{path|/srv/unifi}} with wherever you would prefer to install the UniFi Controller software.
 
<pre>
/
`--etc
  |-- unifi
  |  `-- log
  |-- srv
  |  `-- unifi
  |      |-- bin
  |      |-- conf
  |      |-- data
  |      |-- dl
  |      |-- lib
  |      |-- logs
  |      |-- run
  |      `-- webapps
  |-- run
  |  `-- openrc
  |          `-- s6-scan
  |              `-- unifi --> /etc/unifi
    `-- var
        `-- log
            `-- unifi
</pre>


= Prerequisite Packages =
= Prerequisite Packages =
Line 7: Line 45:
Install <code>openjdk8-jre</code> from the community repository.
Install <code>openjdk8-jre</code> from the community repository.


Edit /etc/apk/respositories and uncomment the appropriate community repository for your Alpine version:
Edit <code>/etc/apk/repositories</code> and uncomment the appropriate community repository for your Alpine version:


<code>http://host.name/alpine_version/community</code>
<code><nowiki>http://host.name/alpine_version/community</nowiki></code>


Update the package cache.
Update the package cache.
Line 27: Line 65:
== s6 ==
== s6 ==


Install [http://www.skarnet.org/software/s6/ s6]
Install [https://www.skarnet.org/software/s6/ s6]
 
<code>apk add s6</code> which is a service supervision suite, for reliably and efficiently starting, stopping and keeping services running.
 
The below shows a schematic process tree of how the UniFi Controller will be started and supervised by s6. The controller is written in Java, hence the Java process and it in turn, launches a dedicated instance of MongoDB to store its configuration and run-time data.


<code>apk add s6</code>
<pre>
init
`-- s6-svscan
    `-- s6-supervise
        |-- s6-log
        `-- java
            `-- mongod
</pre>


= Install UniFi Controller =
= Install UniFi Controller =
Line 35: Line 84:
Create the <code>unifi</code> user and group.
Create the <code>unifi</code> user and group.


<code>adduser -D -H /srv/unifi -g unifi unifi</code>
<code>adduser -D -H -h /srv/unifi unifi</code>


Change to the parent folder within which you wish to install the UniFi Controller.
Change to the parent folder within which you wish to install the UniFi Controller.
Line 43: Line 92:
Download the generic unix archive of the <code>VERSION</code> you wish to install.
Download the generic unix archive of the <code>VERSION</code> you wish to install.


<code>wget http://www.ubnt.com/downloads/unifi/VERSION/UniFi.unix.zip</code>
<code>wget https://www.ubnt.com/downloads/unifi/VERSION/UniFi.unix.zip</code>{{dead_link}}


Unpack the archive.
Unpack the archive.
Line 55: Line 104:
Change ownership.
Change ownership.


<code>chown unifi:unifi unifi</code>
<code>chown -R unifi:unifi unifi</code>


Lock down permissions.
Lock down permissions.
Line 61: Line 110:
<code>chmod o-rwx unifi</code>
<code>chmod o-rwx unifi</code>


= Service Management =
Change into the UniFi bin directory.
 
<code>cd /srv/unifi/bin</code>
 
Remove the existing file.
 
<code>rm mongod</code>
 
Create a symlink to <code>/usr/bin/mongod</code>
 
<code>ln -s /usr/bin/mongod</code>
 
= Configure Service Management =
 
== Create UniFi Service Directory and Files ==


Create an s6 service directory for UniFi.
Create an s6 service directory for UniFi.
Line 95: Line 158:
</pre>
</pre>


Ensure that the run script is executable:
Ensure that the <code>run</code> script is executable:


<code>chmod 755 /etc/unifi/run</code>
<code>chmod 755 /etc/unifi/run</code>
Line 115: Line 178:
Ensure that the log/run script is executable:
Ensure that the log/run script is executable:


<code>chmod 755 /etc/unifi/run</code>
<code>chmod 755 /etc/unifi/log/run</code>
 
== Create log User and Directory ==


Create the <code>log</code> user and group.
Create the <code>log</code> user and group.


<code>adduser -D -H /var/log -g log log</code>
<code>adduser -D -H -h /var/log log</code>


Create the <code>/var/log/unifi</code> directory
Create the <code>/var/log/unifi</code> directory
Line 132: Line 197:


<code>chmod 750 /var/log/unifi</code>
<code>chmod 750 /var/log/unifi</code>
== Create the OpenRC Service Script ==
Open the script file using your favourite editor.
<code>vim /etc/init.d/unifi</code>
Paste the following into it.
<pre>
#!/sbin/openrc-run
name="unifi"
supervisor=s6
s6_service_path="${RC_SVCDIR}/s6-scan/${name}"
depend() {
need net s6-svscan
after firewall
}
start_pre() {
        if [ ! -L "${RC_SVCDIR}/s6-scan/${name}" ]; then
        ln -s "/etc/${name}" "${RC_SVCDIR}/s6-scan/${name}"
fi
}
</pre>
Ensure that the script is executable.
<code>chmod 755 /etc/init.d/unifi</code>
== Start the UniFi Controller Service ==
<code>rc-service unifi start</code>
== Configure the UniFi Controller Service to start on boot ==
<code>rc-update add unifi boot</code>
= Simple Backup Script =
Create <code>/usr/local/bin/unifi-backup</code> using your favourite editor.
'''Note:''' This script assumes the use of s6-svc to control unifi. I will modify it in time, to use rc-service instead.
Paste the following into the file.
<pre>
#!/bin/ash
conf_dir='/etc/unifi'
backup_dir='/srv/backup/unifi'
service_dir='/run/openrc/s6-scan/unifi'
start_state='down'
if s6-svok $service_dir; then
    if s6-svstat -o up,ready $service_dir | grep -q true; then
        echo 'Stopping the UniFi Controller'
        start_state='up'
        s6-svc -d $service_dir
        sleep 3
    fi
else
    echo 'Warning: The UniFi Controller is not supervised'
    exit 1
fi
if s6-svstat -o up $service_dir | grep -q false; then
    echo 'Success: The UniFi Controller was stopped'
else
    echo 'Error: The UniFi Controller is still running'
    exit 1
fi
stamp=`date +%Y-%m-%d_%H%M%S`
mkdir -p $backup_dir
cd $backup_dir
mkdir "data-$stamp"
echo "Backing up to /srv/backup/unifi/data-$stamp.tar.gz"
if rsync -az /srv/unifi/data/ "data-$stamp"; then
    echo '* rsync succeeded'
    if tar czf "data-$stamp.tar.gz" "data-$stamp"; then
        echo '* tar succeeded'
        rm -rf "data-$stamp"
        echo 'Backup succeeded'
    else
        echo 'Backup failed: tar failed'
exit 1
    fi
fi
if [ "$start_state" == 'up' ]; then
    echo 'Starting the UniFi Controller'
    s6-svc -u $service_dir
    sleep 5
    s6-svstat $service_dir
fi
</pre>
[[category:Networking]]

Latest revision as of 09:25, 13 January 2024

This material is proposed for deletion ...

Due to the warning below ⬇️, the unavailability of the image file for the controller (link below has been dead for ages), and Alpine Linux 3.9 being support level "none", there's no reason to keep this article any longer. (Discuss)
Make sure no other pages link here and check the page's history before deleting.

Warning: The Ubiquiti Unifi controller Linux self-contained Java image relies on MongoDB, and MongoDB has been removed from Alpine Linux after version 3.9 due to SPL license changes, so this guide doesn't work.


Introduction

This guide explains how to install the generic Unix UniFi Controller, as available from Ubiquiti Networks. At the time of writing this, a native Alpine Linux package is not available.

Furthermore, this guide uses the incredibly reliable and efficient s6 supervision suite to start and control the UniFi Controller.

A summarized schematic of what will be installed on the filesystem.

The choice of /srv for the UniFi Controller's root directory is based on the fact that it contains both run-time and configuration data, so installing to /usr/local, /opt or /home didn't seem appropriate. Feel free to adjust the steps below, replacing /srv/unifi with wherever you would prefer to install the UniFi Controller software.

/
`--etc
   |-- unifi
   |   `-- log
   |-- srv
   |   `-- unifi
   |       |-- bin
   |       |-- conf
   |       |-- data
   |       |-- dl
   |       |-- lib
   |       |-- logs
   |       |-- run
   |       `-- webapps
   |-- run
   |   `-- openrc
   |          `-- s6-scan
   |              `-- unifi --> /etc/unifi
    `-- var
        `-- log
            `-- unifi

Prerequisite Packages

OpenJDK 8 JRE

Install openjdk8-jre from the community repository.

Edit /etc/apk/repositories and uncomment the appropriate community repository for your Alpine version:

http://host.name/alpine_version/community

Update the package cache.

apk update

Install the package.

apk add openjdk8-jre

MongoDB

Install MongoDB

apk add mongodb

s6

Install s6

apk add s6 which is a service supervision suite, for reliably and efficiently starting, stopping and keeping services running.

The below shows a schematic process tree of how the UniFi Controller will be started and supervised by s6. The controller is written in Java, hence the Java process and it in turn, launches a dedicated instance of MongoDB to store its configuration and run-time data.

init
`-- s6-svscan
    `-- s6-supervise
        |-- s6-log
        `-- java
            `-- mongod

Install UniFi Controller

Create the unifi user and group.

adduser -D -H -h /srv/unifi unifi

Change to the parent folder within which you wish to install the UniFi Controller.

cd /srv

Download the generic unix archive of the VERSION you wish to install.

wget https://www.ubnt.com/downloads/unifi/VERSION/UniFi.unix.zip[Dead Link]

Unpack the archive.

unzip UniFi.unix.zip

Rename the unpacked directory.

mv UniFi unifi

Change ownership.

chown -R unifi:unifi unifi

Lock down permissions.

chmod o-rwx unifi

Change into the UniFi bin directory.

cd /srv/unifi/bin

Remove the existing file.

rm mongod

Create a symlink to /usr/bin/mongod

ln -s /usr/bin/mongod

Configure Service Management

Create UniFi Service Directory and Files

Create an s6 service directory for UniFi.

mkdir -p /etc/unifi/log

Add the run script, using your favourite editor.

vim /etc/unifi/run

Copy and paste the following into it.

#!/bin/ash

user='unifi'
group='unifi'

exec 2>&1

base='/srv/unifi'

if [ -d $base ]; then
    cd $base
    chown -R $user:$group .
    version=`head -1 webapps/ROOT/app-unifi/.version`
    echo "Starting UniFi Controller $version"
    exec s6-setuidgid $user java -jar lib/ace.jar start
else
    echo "Missing $base ... aborting"
    touch down
fi

Ensure that the run script is executable:

chmod 755 /etc/unifi/run

Add the log/run script, using your favourite editor.

vim /etc/unifi/log/run

Copy and paste the following into it.

#!/bin/ash

log_user='log'

exec s6-setuidgid $log_user s6-log -b n20 s1000000 t /var/log/unifi

Ensure that the log/run script is executable:

chmod 755 /etc/unifi/log/run

Create log User and Directory

Create the log user and group.

adduser -D -H -h /var/log log

Create the /var/log/unifi directory

mkdir -p /var/log/unifi

Update the directory ownership.

chown log:log /var/log/unifi

Lock down the permissions.

chmod 750 /var/log/unifi

Create the OpenRC Service Script

Open the script file using your favourite editor.

vim /etc/init.d/unifi

Paste the following into it.

#!/sbin/openrc-run

name="unifi"
supervisor=s6
s6_service_path="${RC_SVCDIR}/s6-scan/${name}"

depend() {
	need net s6-svscan
	after firewall
}

start_pre() {
        if [ ! -L "${RC_SVCDIR}/s6-scan/${name}" ]; then
	        ln -s "/etc/${name}" "${RC_SVCDIR}/s6-scan/${name}"
	fi
}

Ensure that the script is executable.

chmod 755 /etc/init.d/unifi

Start the UniFi Controller Service

rc-service unifi start

Configure the UniFi Controller Service to start on boot

rc-update add unifi boot

Simple Backup Script

Create /usr/local/bin/unifi-backup using your favourite editor.

Note: This script assumes the use of s6-svc to control unifi. I will modify it in time, to use rc-service instead.

Paste the following into the file.

#!/bin/ash

conf_dir='/etc/unifi'
backup_dir='/srv/backup/unifi'
service_dir='/run/openrc/s6-scan/unifi'

start_state='down'

if s6-svok $service_dir; then
    if s6-svstat -o up,ready $service_dir | grep -q true; then
        echo 'Stopping the UniFi Controller'
        start_state='up'
        s6-svc -d $service_dir
        sleep 3
    fi
else
    echo 'Warning: The UniFi Controller is not supervised'
    exit 1
fi

if s6-svstat -o up $service_dir | grep -q false; then
    echo 'Success: The UniFi Controller was stopped'
else
    echo 'Error: The UniFi Controller is still running'
    exit 1
fi

stamp=`date +%Y-%m-%d_%H%M%S`

mkdir -p $backup_dir
cd $backup_dir
mkdir "data-$stamp"

echo "Backing up to /srv/backup/unifi/data-$stamp.tar.gz"

if rsync -az /srv/unifi/data/ "data-$stamp"; then
    echo '* rsync succeeded'
    if tar czf "data-$stamp.tar.gz" "data-$stamp"; then
        echo '* tar succeeded'
        rm -rf "data-$stamp"
        echo 'Backup succeeded'
    else
        echo 'Backup failed: tar failed'
	exit 1
    fi
fi

if [ "$start_state" == 'up' ]; then
    echo 'Starting the UniFi Controller'
    s6-svc -u $service_dir
    sleep 5
    s6-svstat $service_dir
fi