Alpine Linux - User contributions [en]

UniFi Controller

2019-09-07T15:38:03Z

Kgzm: Fix commands around creating the /srv/unifi directory and setting up ownership

= Introduction =

This guide explains how to install the generic Unix UniFi Controller, as available from [http://www.ubnt.com/ Ubiquity Networks]. At the time of writing this, a native Alpine Linux package is not available.

Furthermore, this guide uses the incredibly reliable and efficient [http://www.skarnet.org/software/s6/ s6] supervision suite to start and control the UniFi Controller.

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

The choice of <code>/srv</code> for the UniFi Controller's root directory is based on the fact that it contains both run-time and configuration data, so installing to <code>/usr/local</code>, <code>/opt</code> or <code>/home</code> didn't seem apt. Feel free to adjust the steps below, replacing <code>/srv/unifi</code> 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 =

== OpenJDK 8 JRE ==

Install <code>openjdk8-jre</code> from the community repository.

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

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

Update the package cache.

<code>apk update</code>

Install the package.

<code>apk add openjdk8-jre</code>

== MongoDB ==

Install MongoDB

<code>apk add mongodb</code>

== s6 ==

Install [http://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.

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

= Install UniFi Controller =

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

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

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

<code>cd /srv</code>

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>

Unpack the archive.

<code>unzip UniFi.unix.zip</code>

Rename the unpacked directory.

<code>mv UniFi unifi</code>

Change ownership.

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

Lock down permissions.

<code>chmod o-rwx unifi</code>

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.

<code>mkdir -p /etc/unifi/log</code>

Add the <code>run</code> script, using your favourite editor.

<code>vim /etc/unifi/run</code>

Copy and paste the following into it.

<pre>
#!/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
</pre>

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

<code>chmod 755 /etc/unifi/run</code>

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

<code>vim /etc/unifi/log/run</code>

Copy and paste the following into it.

<pre>
#!/bin/ash

log_user='log'

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

Ensure that the log/run script is executable:

<code>chmod 755 /etc/unifi/run</code>

== Create log User and Directory ==

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

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

Create the <code>/var/log/unifi</code> directory

<code>mkdir -p /var/log/unifi</code>

Update the directory ownership.

<code>chown log:log /var/log/unifi</code>

Lock down the permissions.

<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>

UniFi Controller

2019-09-07T15:31:27Z

Kgzm: adduser -h should be used to assign home directory rather than -H

= Introduction =

This guide explains how to install the generic Unix UniFi Controller, as available from [http://www.ubnt.com/ Ubiquity Networks]. At the time of writing this, a native Alpine Linux package is not available.

Furthermore, this guide uses the incredibly reliable and efficient [http://www.skarnet.org/software/s6/ s6] supervision suite to start and control the UniFi Controller.

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

The choice of <code>/srv</code> for the UniFi Controller's root directory is based on the fact that it contains both run-time and configuration data, so installing to <code>/usr/local</code>, <code>/opt</code> or <code>/home</code> didn't seem apt. Feel free to adjust the steps below, replacing <code>/srv/unifi</code> 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 =

== OpenJDK 8 JRE ==

Install <code>openjdk8-jre</code> from the community repository.

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

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

Update the package cache.

<code>apk update</code>

Install the package.

<code>apk add openjdk8-jre</code>

== MongoDB ==

Install MongoDB

<code>apk add mongodb</code>

== s6 ==

Install [http://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.

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

= Install UniFi Controller =

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

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

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

<code>cd /srv</code>

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>

Unpack the archive.

<code>unzip UniFi.unix.zip</code>

Rename the unpacked directory.

<code>mv UniFi unifi</code>

Change ownership.

<code>chown unifi:unifi unifi</code>

Lock down permissions.

<code>chmod o-rwx unifi</code>

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.

<code>mkdir -p /etc/unifi/log</code>

Add the <code>run</code> script, using your favourite editor.

<code>vim /etc/unifi/run</code>

Copy and paste the following into it.

<pre>
#!/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
</pre>

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

<code>chmod 755 /etc/unifi/run</code>

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

<code>vim /etc/unifi/log/run</code>

Copy and paste the following into it.

<pre>
#!/bin/ash

log_user='log'

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

Ensure that the log/run script is executable:

<code>chmod 755 /etc/unifi/run</code>

== Create log User and Directory ==

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

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

Create the <code>/var/log/unifi</code> directory

<code>mkdir -p /var/log/unifi</code>

Update the directory ownership.

<code>chown log:log /var/log/unifi</code>

Lock down the permissions.

<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>