From eea9da2f42c23fae72bb5b67c51dd38ab3a92a8d Mon Sep 17 00:00:00 2001 From: Corey Farrell Date: Sun, 18 Jun 2017 20:24:04 -0400 Subject: Core: Add support for systemd socket activation. This change adds support for socket activation of certain SOCK_STREAM listeners in Asterisk: * AMI / AMI over TLS * CLI * HTTP / HTTPS Example systemd units are provided. This support extends to any socket which is initialized using ast_tcptls_server_start, so any unknown modules using this function will support socket activation. Asterisk continues to function as normal if socket activation is not enabled or if systemd development headers are not available during build. ASTERISK-27063 #close Change-Id: Id814ee6a892f4b80d018365c8ad8d89063474f4d --- contrib/systemd/README.txt | 119 ++++++++++++++++++++++++++++++++++ contrib/systemd/asterisk-ami.socket | 10 +++ contrib/systemd/asterisk-amis.socket | 10 +++ contrib/systemd/asterisk-cli.socket | 13 ++++ contrib/systemd/asterisk-http.socket | 11 ++++ contrib/systemd/asterisk-https.socket | 11 ++++ contrib/systemd/asterisk.service | 27 ++++++++ contrib/systemd/asterisk.socket | 26 ++++++++ 8 files changed, 227 insertions(+) create mode 100644 contrib/systemd/README.txt create mode 100644 contrib/systemd/asterisk-ami.socket create mode 100644 contrib/systemd/asterisk-amis.socket create mode 100644 contrib/systemd/asterisk-cli.socket create mode 100644 contrib/systemd/asterisk-http.socket create mode 100644 contrib/systemd/asterisk-https.socket create mode 100644 contrib/systemd/asterisk.service create mode 100644 contrib/systemd/asterisk.socket (limited to 'contrib') 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 -- cgit v1.2.3