Systemd

This page describes how to run lykos under a service account using systemd on Linux. In this configuration, the bot will automatically start with the system, and restart automatically in case of an abnormal exit. This guide assumes that you have root access to the system and want to install the bot as a system service (which is recommended); if you don't have root access, you can still install the bot as a user service, but this has some caveats (see below).

Ensure prerequisites are met
Before you begin, please ensure that your system meets all prerequisites for running the bot.

Create a service account
First, create a service user account to run the bot under. We'll name the account "lykos" and create the service account's home directory as, but you can pick anything you'd like. Run the following commands as root:

addgroup --system lykos adduser --system --home /var/lib/lykos --shell /usr/sbin/nologin --ingroup lykos --disabled-login

Clone or move lykos files to home directory
Next, you'll need to clone a copy of the bot (if setting up a brand new lykos) or move an existing copy of the bot to the lykos user's home directory. It is possible to run multiple copies of the bot (e.g., for different channels or networks); just put each instance of the bot in its own directory in the lykos user's home directory.

For this example, we'll assume that you want to clone a single new copy of the bot. In the lykos home directory, run the following command as root:

git clone https://github.com/lykoss/lykos.git

You can change the directory the bot is cloned to, as well. For example, if you want to clone the bot into a directory called "freenode", you might run the following:

git clone https://github.com/lykoss/lykos.git freenode

In addition, for any new clones of the bot, ensure you are running in the "stable" branch by running the command.

Configure the bot (if necessary)
If you're setting up one or more new lykos instances, please take a moment now to configure them (see here).

Verify file permissions
You'll next need to make sure that all files within the lykos home directory have all the proper permissions set. Run the following commands as root:

chown -R lykos:lykos /var/lib/lykos chmod -R ug=rwX,o= /var/lib/lykos

Create systemd service units
Use the command  to navigate to your systemd services configuration. Use your favorite text editor to create a new service unit file like this:

[Unit] Description=lykos, the werewolf game for IRC! After=syslog.target network.target [Service] User=lykos ExecStart=/usr/bin/python3 PATH_TO_WOLFBOT.PY WorkingDirectory=PATH_TO_BOT_DIRECTORY Type=simple KillSignal=2 SendSIGKILL=yes Restart=on-failure [Install] WantedBy=multi-user.target

In the unit file, replace PATH_TO_WOLFBOT.PY with the absolute path to the wolfbot.py file for that instance of lykos - for example,. In addition, replace PATH_TO_BOT_DIRECTORY with the absolute path of the directory containing wolfbot.py - in this example,. You may also need to change the path to your python executable, though the one given in the example should work fine. If you do need to change it, remember that you must use absolute paths! The filename of the service unit file should be something unique for each instance of the bot, but must end with  - for example,. If you go this route, you will need to create a service unit file for each instance of the bot you wish to run.

Alternatively, if you wish to run multiple instances of lykos, you can save some effort by using a templated service unit to launch so-called "instanced" services. If you follow the pattern of putting each instance of lykos you wish to run in its own subfolder in the lykos user's home directory (e.g.,,  ), then in the service unit file for lykos, replace PATH_TO_WOLFBOT.PY with  , and PATH_TO_BOT_DIRECTORY with. Save the service unit file as  (the @ is important!).

Once you have created all the unit files for your lykos instances (or created the templated unit file), reload your systemd configuration by running the command  as root.


 * If you created one or more service unit files for your lykos bot(s): Start your bots by calling (again, as root), where unit is the same name you gave the service unit file.  For example, if you created your lykos's service unit file as  , to start the bot you would call   or   (both will work).  You can also stop the bot by running the command  , or stop then restart by doing.


 * If you created a single templated unit file for all your lykos instances (i.e., you created a  file): Start your bots by calling as root , where instance is the name of the subdirectory the bot is saved in.  For example, if the instance of lykos you wish to start is saved at  , you would start it with  ; to start the one saved at  , you would start it with  .  Specifically, systemd will take the bit after the @ and substitute it for   in the system template unit file you created.  An unlimited number of lykos instances can be started in this way, as long as each instance has a unique identifier after the @.  Instances can be stopped by doing  , and restarted using  .  Using this route, you can also stop all your running lykos instances by running the command  , and restart all your currently running lykos instances by running the command   (but note that you cannot cold-start all your lykos instances together in this fashion).

To enable the bot(s) to start automatically when the system boots up, run the command  for each instance. The command  will likewise prevent the bot(s) from starting automatically when the system boots up, but you'll still be able to manually start the bot. By default, newly-created systemd services do not start at boot.

Once they are running as systemd services, you can view the logs and output from your lykos bot(s) by running the command.

There are other options you can add to your service unit files to customize how systemd controls the bot, though note that the default will work fine for almost all cases. Please consult the  and   manpages for more details. Remember that you must call  after making any changes to the unit files!

User service workaround
If you don't have root access to a system, it is possible to run the bot under your own user account (called a user service), but this has some caveats. Firstly, by default, user services are terminated when a user logs out of the system (more accurately, when all of a user's sessions are closed). This means that your lykos bot(s) will be killed when you log out of a server, for example, even if the server is itself still running. This behavior can be changed by the system administrator or another user with root access by running the command (as root), where username is your username. With "linger" enabled, the bot(s) will persist in the background even after you have logged out. In addition, user services by default do not start when the system boots up, but when the user logs in for the first time. This is also changed by setting  on your account, which will cause the service to start up with the system, even if you haven't logged in yet.

'''Running as a user service is not recommended if at all avoidable. If you have root access to a system, running as a system service is always preferred!'''

To install the bot as a user service, follow the same steps as above, but with the following alterations:
 * Don't create a separate service account for lykos (because you can't)
 * You'll be cloning and otherwise working with the bot files in your own home directory
 * There's no need to verify the file permissions, since you're doing everything under your own user account
 * Instead of creating the systemd service unit files in, you will instead need to create them in  , where username is again your own username.  One or more of these folders may not exist; if so, you can just create them with.
 * When writing the service unit files for lykos, do not include the line starting with, and replace   with
 * When running any  commands, instead run  .  For example,   becomes   and   becomes.
 * To view the logs and output of your bots running as user services, run the command

Note that when configured as a user service, running  on your lykos service unit(s) will by default cause the bot to start up when you log in for the first time, not when the system boots up (and the bot will be killed when you log out). If you have had the  option set on your account, however, the bot will start up with the system, as with a normal system service (and the bot will stay alive when you log out).

When trying to run your bot as a user service, if you see the error "Failed at step GROUP spawning /usr/bin/python3: Operation not permitted", ensure that you removed the  line from the service unit file. Again, remember that you must run  anytime after editing a unit file.