Merge "Core: Add support for systemd socket activation." into 15

8 files changed, 227 insertions, 0 deletions

diff --git a/contrib/systemd/README.txt b/contrib/systemd/README.txt
new file mode 100644
index 000000000..3225641f4
--- /dev/null
+++ b/contrib/systemd/README.txt
@@ -0,0 +1,119 @@
+SystemD Socket Activation for Asterisk
+======================================
+
+This folder contains sample unit files which can be used as the basis of a
+socket activated Asterisk deployment.  Socket activation support currently
+extends to the following listeners:
+
+* Asterisk Command-line Interface
+* Asterisk Manager Interface (clear text and TLS)
+* Builtin HTTP / HTTPS server
+
+The primary use case of this feature is to allow Asterisk to be started by
+other services through use of AMI, CLI or REST API.
+
+
+Security
+========
+
+Care must be take if enabling socket activation on any IP:PORT that is not
+protected by a firewall.  Any user that can reach any socket activation
+port can start Asterisk, even if they do not have valid credentials to sign
+into the service in question.  Enabling HTTP socket activation on a system
+which provides SIP over websockets would allow remote users to start Asterisk
+any time the HTTP socket is running.
+
+This functionality bypasses the normal restriction where only 'root' can start
+a service.  Enabling AMI socket activation allows any user on the local server
+to start Asterisk by running 'telnet localhost 5038'.
+
+CLI activation is secured by the combination of SocketUser, SocketGroup and
+SocketMode settings in the systemd socket.  Only local users with access will
+be able to start asterisk by using CLI.
+
+
+Separate .socket units or a single unit
+=======================================
+
+Asterisk is a complex system with many components which can be enabled or
+disabled individually.  Using socket activation requires deciding to use
+a single socket file or multiple separate socket files.
+
+The remainder of this README assumes separate socket units are used for each
+listener.
+
+
+Service and Socket files
+========================
+
+All .socket and .service examples in this folder use "reasonable" default
+paths for Linux.  Depending on your distribution and ./configure options
+you may need to modify these before installing.  The files are meant to
+be examples rather than files to be blindly installed.
+
+
+Installing and enabling socket units
+====================================
+
+Modify socket files as desired.  Install them to a location where systemd
+will find them.  pkg-config can be used to determine an appropriate location.
+
+For socket files to be managed directly by the local administrator:
+    pkg-config systemd --variable systemdsystemconfdir
+
+For socket files to be deployed by package manager:
+    pkg-config systemd --variable systemdsystemunitdir
+
+
+After installing socket files you must run 'systemctl daemon-reload' for
+systemd to read the added/modified units.  After this you can enable the
+desired sockets, for example to enable AMI:
+    systemctl enable asterisk-ami.socket
+
+
+Socket Selection
+================
+
+Asterisk configuration is unchanged by use of socket activation.  When a
+component that supports socket activation starts a listener in Asterisk,
+any sockets provided by systemd are iterated.  The systemd socket is used
+when the bound address configured by Asterisk is an exact match with the
+address given by the ListenStream setting in the systemd socket.
+
+
+Command-line Interface
+======================
+
+Symbolic links do not appear to be resolved when checking the CLI listener.
+This may be of concern since /var/run is often a symbolic link to /run. Both
+Asterisk and systemd must use /var/run, or both must use /run.  Mismatching
+will result in service startup failure.
+
+When socket activation is used for Asterisk CLI some asterisk.conf options
+are ignored.  The following options from the [files] section are ignored
+and must instead be set by the systemd socket file.
+* astctlowner - use SocketUser
+* astctlgroup - use SocketGroup
+* astctlpermissions - use SocketMode
+
+See asterisk-cli.socket for an example of these settings.
+
+
+Stopping Asterisk
+=================
+
+Some existing asterisk.service files use CLI 'core stop now' for the ExecStop
+command.  It is not recommended to use CLI to stop Asterisk on systems where
+CLI socket activation is enabled.  If Asterisk fails to start systemd still
+tries running the ExecStop command.  This can result in an loop where ExecStop
+causes CLI socket activation to start Asterisk again.  A better way to deal
+with shutdown is to use Type=notify and do not specify an ExecStop command.
+See the example asterisk.service.
+
+
+Unused Sockets
+==============
+
+Asterisk makes no attempt to check for sockets provided by systemd that are not
+used.  It is the users responsibility to only provide sockets which Asterisk is
+configured to use.
diff --git a/contrib/systemd/asterisk-ami.socket b/contrib/systemd/asterisk-ami.socket
new file mode 100644
index 000000000..1fd45e4cb
--- /dev/null
+++ b/contrib/systemd/asterisk-ami.socket
@@ -0,0 +1,10 @@
+[Unit]
+Description=Asterisk Manager Interface Socket
+
+[Socket]
+Service=asterisk.service
+ListenStream=0.0.0.0:5038
+
+[Install]
+WantedBy=sockets.target
+RequiredBy=asterisk.service
diff --git a/contrib/systemd/asterisk-amis.socket b/contrib/systemd/asterisk-amis.socket
new file mode 100644
index 000000000..c17cee3e2
--- /dev/null
+++ b/contrib/systemd/asterisk-amis.socket
@@ -0,0 +1,10 @@
+[Unit]
+Description=Asterisk Manager Interface TLS Socket
+
+[Socket]
+Service=asterisk.service
+ListenStream=0.0.0.0:5039
+
+[Install]
+WantedBy=sockets.target
+RequiredBy=asterisk.service
diff --git a/contrib/systemd/asterisk-cli.socket b/contrib/systemd/asterisk-cli.socket
new file mode 100644
index 000000000..9161a7be4
--- /dev/null
+++ b/contrib/systemd/asterisk-cli.socket
@@ -0,0 +1,13 @@
+[Unit]
+Description=Asterisk Command-line Interface Socket
+
+[Socket]
+Service=asterisk.service
+ListenStream=/var/run/asterisk/asterisk.ctl
+SocketUser=asterisk
+SocketGroup=asterisk
+SocketMode=0660
+
+[Install]
+WantedBy=sockets.target
+RequiredBy=asterisk.service
diff --git a/contrib/systemd/asterisk-http.socket b/contrib/systemd/asterisk-http.socket
new file mode 100644
index 000000000..e6862b5b9
--- /dev/null
+++ b/contrib/systemd/asterisk-http.socket
@@ -0,0 +1,11 @@
+[Unit]
+Description=Asterisk HTTP Socket
+
+[Socket]
+Service=asterisk.service
+FreeBind=true
+ListenStream=127.0.0.1:8088
+
+[Install]
+WantedBy=sockets.target
+RequiredBy=asterisk.service
diff --git a/contrib/systemd/asterisk-https.socket b/contrib/systemd/asterisk-https.socket
new file mode 100644
index 000000000..d9240dd91
--- /dev/null
+++ b/contrib/systemd/asterisk-https.socket
@@ -0,0 +1,11 @@
+[Unit]
+Description=Asterisk HTTPS Socket
+
+[Socket]
+Service=asterisk.service
+FreeBind=true
+ListenStream=127.0.0.1:8089
+
+[Install]
+WantedBy=sockets.target
+RequiredBy=asterisk.service
diff --git a/contrib/systemd/asterisk.service b/contrib/systemd/asterisk.service
new file mode 100644
index 000000000..c3d46483c
--- /dev/null
+++ b/contrib/systemd/asterisk.service
@@ -0,0 +1,27 @@
+[Unit]
+Description=Asterisk PBX and telephony daemon.
+After=network.target
+
+[Service]
+Type=notify
+Environment=HOME=/var/lib/asterisk
+WorkingDirectory=/var/lib/asterisk
+User=asterisk
+Group=asterisk
+ExecStart=/usr/sbin/asterisk -mqf -C /etc/asterisk/asterisk.conf
+ExecReload=/usr/sbin/asterisk -rx 'core reload'
+
+#Nice=0
+#UMask=0002
+LimitCORE=infinity
+#LimitNOFILE=
+Restart=always
+RestartSec=4
+
+# Prevent duplication of logs with color codes to /var/log/messages
+StandardOutput=null
+
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
diff --git a/contrib/systemd/asterisk.socket b/contrib/systemd/asterisk.socket
new file mode 100644
index 000000000..afdca0df7
--- /dev/null
+++ b/contrib/systemd/asterisk.socket
@@ -0,0 +1,26 @@
+[Unit]
+Description=Asterisk Sockets
+
+[Socket]
+FreeBind=true
+SocketUser=asterisk
+SocketGroup=asterisk
+SocketMode=0660
+
+# CLI
+ListenStream=/var/run/asterisk/asterisk.ctl
+# AMI
+ListenStream=0.0.0.0:5038
+# AMIS
+ListenStream=0.0.0.0:5039
+# HTTP
+ListenStream=127.0.0.1:8088
+# HTTPS
+ListenStream=127.0.0.1:8089
+# chan_sip TCP
+ListenStream=0.0.0.0:5060
+# chan_sip TLS
+ListenStream=0.0.0.0:5061
+
+[Install]
+WantedBy=sockets.target