Systemd integration

Using bluealsa with systemd

Systemd (https://www.freedesktop.org/wiki/Software/systemd/) is now the most common system and service manager on mainstream linux distributions. This article describes how to manage bluealsa with systemd.

Service unit file

The bluealsa daemon should be managed as a service unit within systemd. It may be defined as type "simple" or type "dbus". The only difference is in the handling of consequent units by systemd (i.e. units that are set to start "After=bluealsa.service") - the choice does not affect the behaviour of bluealsa itself.

For "simple" type, any unit that is set to start after bluealsa will be started as soon as the bluealsa daemon has been started. For "dbus" type, those units will not be started until bluealsa has acquired the D-Bus bus name set by "Busname=". Since bluealsa is unable to perform any useful function until that name is acquired, we recommend using type "dbus".

To manage bluealsa with systemd, create the following unit file:

/etc/systemd/system/bluealsa.service

[Unit]
Description=Bluealsa daemon
Documentation=https://github.com/Arkq/bluez-alsa/
After=dbus-org.bluez.service
Requires=dbus-org.bluez.service

[Service]
Type=dbus
BusName=org.bluealsa
EnvironmentFile=-/etc/default/bluealsa
ExecStart=/usr/bin/bluealsa $OPTIONS
Restart=on-failure
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
RemoveIPC=true
RestrictAddressFamilies=AF_UNIX AF_BLUETOOTH
; Also non-privileged can user be used
; this example assumes a user and group called 'bluealsa' exist
;User=bluealsa
;Group=bluealsa
;NoNewPrivileges=true

[Install]
WantedBy=bluetooth.target

Download the file bluealsa.service

If you wish to pass some command-line options to bluealsa when it starts, define the environment variable OPTIONS in the file:

/etc/default/bluealsa

For example:

OPTIONS="-p a2dp-source -p a2dp-sink"

Inform systemd of the new service by:

$ sudo systemctl daemon-reload

Notes:

The use of "dbus-org.bluez.service" and "bluetooth.target" in the systemd unit file above should work in the majority of cases; but note that a particular distribution may choose to use different names, and in that case you would have to consult the documentation for your distribution.
If you want the bluealsa daemon to run under a dedicated account (i.e. non-root), you should also modify dbus configuration. Modify the file /etc/dbus-1/system.d/bluealsa.conf with this content:

<!DOCTYPE busconfig PUBLIC
 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>

    <policy user="bluealsa">
        <allow own_prefix="org.bluealsa"/>
        <allow send_destination="org.bluealsa"/>
        <allow send_destination="org.bluez"/>
    </policy>

    <policy group="audio">
        <allow send_destination="org.bluealsa"/>
    </policy>

</busconfig>

On some systems the dbus change can be made effective by:

$ sudo systemctl reload dbus.service

However, on my Ubuntu system this has no effect on D-Bus and it appears to be necessary to reboot in order to change the dbus configuration.

Starting (and stopping) bluealsa

start at boot

Bluealsa is designed to use minimal system resources when idle, and so on most systems it is acceptable (and advisable) to start it at boot and leave it running. It can be set to start at boot with:

$ sudo systemctl enable bluealsa.service

To cancel this, so that bluealsa does not start on subsequent boots, use:

$ sudo systemctl disable bluealsa.service

start manually from the command line

Bluealsa can be started, and stopped, using the commands:

$ sudo systemctl start bluealsa.service

$ sudo systemctl stop bluealsa.service

start on demand by a D-Bus client

If bluealsa is only required when certain clients are running, D-Bus can be configured to start it automatically when a client requests it. This may be useful, for example, with bluealsa-aplay; however, for clients such as aplay or other alsa applications, in this case no bluetooth audio devices will yet be connected, so the client request will fail. To enable this feature, create the following file:

/usr/share/dbus-1/system-services/org.bluealsa.service

[D-BUS Service]
Name=org.bluealsa
Exec=/bin/false
User=root
SystemdService=bluealsa.service

Download the file org.bluealsa.service

Note that once started in this way, bluealsa will continue to run as D-Bus does not stop it when the client terminates.

Running bluealsa-aplay as a systemd service

bluealsa-aplay can also be used as a systemd service. For example, create this systemd unit file:

/etc/systemd/system/bluealsa-aplay.service

[Unit]
Description=Bluealsa audio player
Documentation=https://github.com/Arkq/bluez-alsa/
Wants=bluealsa.service

[Service]
Type=simple
;default to all devices - can be overridden in the EnvironmentFile
Environment="BT_ADDR=00:00:00:00:00:00"
EnvironmentFile=-/etc/default/bluealsa-aplay
ExecStart=/usr/bin/bluealsa-aplay $OPTIONS $BT_ADDR
Restart=on-failure
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
RemoveIPC=true
RestrictAddressFamilies=AF_UNIX
; Also non-privileged can user be used
; this example assumes a user called 'bluealsa-aplay' exists in the group 'audio'
;User=bluealsa-aplay
;Group=audio
;NoNewPrivileges=true

[Install]
WantedBy=multiuser.target

Download the file bluealsa-aplay.service

If you wish to pass some command-line options to bluealsa-aplay when it starts, create the file:

/etc/default/bluealsa-aplay

In this file, define the environment variables OPTIONS to set non-default options and/or BT_ADDR to restrict the devices that will be accepted.