install_prereq: Add Arch Linux.
[asterisk/asterisk.git] / contrib / systemd / README.txt
1 SystemD Socket Activation for Asterisk
2 ======================================
3
4 This folder contains sample unit files which can be used as the basis of a
5 socket activated Asterisk deployment.  Socket activation support currently
6 extends to the following listeners:
7
8 * Asterisk Command-line Interface
9 * Asterisk Manager Interface (clear text and TLS)
10 * Builtin HTTP / HTTPS server
11
12 The primary use case of this feature is to allow Asterisk to be started by
13 other services through use of AMI, CLI or REST API.
14
15
16 Security
17 ========
18
19 Care must be take if enabling socket activation on any IP:PORT that is not
20 protected by a firewall.  Any user that can reach any socket activation
21 port can start Asterisk, even if they do not have valid credentials to sign
22 into the service in question.  Enabling HTTP socket activation on a system
23 which provides SIP over websockets would allow remote users to start Asterisk
24 any time the HTTP socket is running.
25
26 This functionality bypasses the normal restriction where only 'root' can start
27 a service.  Enabling AMI socket activation allows any user on the local server
28 to start Asterisk by running 'telnet localhost 5038'.
29
30 CLI activation is secured by the combination of SocketUser, SocketGroup and
31 SocketMode settings in the systemd socket.  Only local users with access will
32 be able to start asterisk by using CLI.
33
34
35 Separate .socket units or a single unit
36 =======================================
37
38 Asterisk is a complex system with many components which can be enabled or
39 disabled individually.  Using socket activation requires deciding to use
40 a single socket file or multiple separate socket files.
41
42 The remainder of this README assumes separate socket units are used for each
43 listener.
44
45
46 Service and Socket files
47 ========================
48
49 All .socket and .service examples in this folder use "reasonable" default
50 paths for Linux.  Depending on your distribution and ./configure options
51 you may need to modify these before installing.  The files are meant to
52 be examples rather than files to be blindly installed.
53
54
55 Installing and enabling socket units
56 ====================================
57
58 Modify socket files as desired.  Install them to a location where systemd
59 will find them.  pkg-config can be used to determine an appropriate location.
60
61 For socket files to be managed directly by the local administrator:
62     pkg-config systemd --variable systemdsystemconfdir
63
64 For socket files to be deployed by package manager:
65     pkg-config systemd --variable systemdsystemunitdir
66
67
68 After installing socket files you must run 'systemctl daemon-reload' for
69 systemd to read the added/modified units.  After this you can enable the
70 desired sockets, for example to enable AMI:
71     systemctl enable asterisk-ami.socket
72
73
74 Socket Selection
75 ================
76
77 Asterisk configuration is unchanged by use of socket activation.  When a
78 component that supports socket activation starts a listener in Asterisk,
79 any sockets provided by systemd are iterated.  The systemd socket is used
80 when the bound address configured by Asterisk is an exact match with the
81 address given by the ListenStream setting in the systemd socket.
82
83
84 Command-line Interface
85 ======================
86
87 Symbolic links do not appear to be resolved when checking the CLI listener.
88 This may be of concern since /var/run is often a symbolic link to /run. Both
89 Asterisk and systemd must use /var/run, or both must use /run.  Mismatching
90 will result in service startup failure.
91
92 When socket activation is used for Asterisk CLI some asterisk.conf options
93 are ignored.  The following options from the [files] section are ignored
94 and must instead be set by the systemd socket file.
95 * astctlowner - use SocketUser
96 * astctlgroup - use SocketGroup
97 * astctlpermissions - use SocketMode
98
99 See asterisk-cli.socket for an example of these settings.
100
101
102 Stopping Asterisk
103 =================
104
105 Some existing asterisk.service files use CLI 'core stop now' for the ExecStop
106 command.  It is not recommended to use CLI to stop Asterisk on systems where
107 CLI socket activation is enabled.  If Asterisk fails to start systemd still
108 tries running the ExecStop command.  This can result in an loop where ExecStop
109 causes CLI socket activation to start Asterisk again.  A better way to deal
110 with shutdown is to use Type=notify and do not specify an ExecStop command.
111 See the example asterisk.service.
112
113
114 Unused Sockets
115 ==============
116
117 Asterisk makes no attempt to check for sockets provided by systemd that are not
118 used.  It is the users responsibility to only provide sockets which Asterisk is
119 configured to use.