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.