Custom User Services

Since i am running lots of various shaped and managed services, i needed an efficient and simple way to automatically start and stop them.

Gentoo already provides a good approach to starting and stopping services called SysVInit that can easily take care of all the services installed by the system, like the NGINX reverse proxy and similar stuff. In general, it can handle directly anything you have installed via emerge.

What about thos (lots of) services you are installing manually because they are not in portage or will never be in portage (ex: docker/podman based services…)? Gentoo give you a neat way to add your own scripts under /etc/local.d.

Let me show how i am managing this approach.


Local.d is the last service running in the SysVInit world just before the system is all ready. You can add your own custom startup scripts under the folder /etc/local.d with the following syntax:


and, if those script are executable (+x), then will be called at startup and shutdown respectively.

See here for more details.

Indeed this is not considered officially a good place to do what i will show you should do, but YMMV and i find it a safer and less invasive way to start all our non-system services.

The Approach

You want to streamline deployment of services as much as possible, thus you do not want to manually manage tons of start/stop scripts.

One way would be to create your own init scripts and put them under /etc/init.d, which is mostly overkill for most of the services you will be installing. Moreover, i prefer to keep my system and my services as much separated as possible.

The other way is to use local.d service leveraging a specific script with symlinks: the idea is to use one script for most of the services, and just create a symlink to the start and stop scripts themselves.

Assuming you have a service called myservice, which is a podman container, run as myuser user, all you need to do it:

cd /etc/local.d
ln -s 50-myservice-myuser-podman.start 
ln -s 50-myservice-myuser-podman.stop

and that's it. This will automatically create the /var/run/ file for service-monitoring, and allow proper start and stop of the service. This will require the usual docker-compose.yml file in the myuser folder.

Similarly, for a simple non-containerized service:

cd /etc/local.d
ln -s 50-mynormalservice-myotheruser-service.start 
ln -s 50-mynormalservice-myotheruser-service.stop

This will require a file called service_mynormalservice_start myotheruser folder, like this:

ARGUMENTS=(my service arguments)

The Script

Leveraging great bash lore, here is the beast /etc/local.d/
# Make a symlink to with this syntax:
#  - XX-myservice-user-type.action
# where:
#  - XX is a number (ex: 10)
#  - myservice will be the name of the service (it will create /var/run/ for checking service status)
#  - user is the user the service will run as. Can be omitted, in this case use two "--", and user=service
#  - type is one of:
#        - podman: the service is a podman-compose based containeration
#        - script: the service is managed by a script ($user_home/ or $user_home/, and $user_home/ (optional))
#        - service: the service command is specified inside a service_${service}_start file in the user home folder
#  - action is either start or stop
test ! -d "${LOG_PATH}" && mkdir "${LOG_PATH}"
test -z ${USER} && USER=${SERVICE}
passwd_entry=$(getent passwd ${USER}) || exit 255
USER_HOME=$(echo ${passwd_entry} | cut -d: -f 6)
echo "$(date): ${ACTION}-ing service '${SERVICE}' for user '${USER}', as '${TYPE}' (${USER_HOME})" >> ${actions_logs}
if [ "${ACTION}" = "start" ]
        test -e "${LOG_PATH}/${SERVICE}" || {
                mkdir "${LOG_PATH}/${SERVICE}"
        } && chown -R ${USER} "${LOG_PATH}/${SERVICE}"
        extra_opts=(-1 "${LOG_PATH}/${SERVICE}/${SERVICE}.out.log" -2 "${LOG_PATH}/${SERVICE}/${SERVICE}.err.log")
        if [ "${TYPE}" = "podman" ]
                COMMAND="$(which podman)"
                ARGUMENTS=(compose up)
                echo "          ... ensuring nat table is loaded ..." >> ${actions_logs}
                iptables -L -t nat &> /dev/null
                echo "          ... creating '${SERVICE}-net' ..." >> ${actions_logs}
                podman network create ${SERVICE}-net &> /dev/null
                echo "          ... running a 'podman compose down' just in case ..." >> ${actions_logs}
                su - "${USER}" -c "$(which podman) compose down" &> /dev/null
        elif [ "${TYPE}" = "script" ]
                echo "          ... checking for start scripts ..." >> ${actions_logs}
                test -e ${start_script} || start_script="${USER_HOME}/${SERVICE}.sh"
                echo "          ... detected '${start_script}' ..." >> ${actions_logs}
        elif [ "${TYPE}" = "service" ]
                echo "          ... checking for config settings ..." >> ${actions_logs}
                test -e "${source_script}" || {
                        echo "Error, missing '${source_script}'" >> ${actions_logs}
                        exit 255
                echo "          ... sourcing '${source_script}'..." >> ${actions_logs}
                source "${source_script}"
        action=(-b -m --start "${COMMAND}" -- ${ARGUMENTS[@]})
elif [ "${ACTION}" = "stop" ]
        if [ "${TYPE}" = "podman" ]
                echo "          ... running 'podman compose down' ..." >> ${actions_logs}
                su - "${USER}" -c "$(which podman) compose down" &> /dev/null
                action=(--stop "${SERVICE}")
        elif [ "${TYPE}" = "script" ]
                echo "          ... checking for stop script ..." >> ${actions_logs}
                test -e "${stop_script}" && {
                        echo "          ... running '${stop_script}' ..." >> ${actions_logs}
                        su - ${USER} -c "${stop_script}"
        elif [ "${TYPE}" = "service" ]
        action=(--stop ${SERVICE})
echo start-stop-daemon -p /var/run/${SERVICE}.pid ${extra_opts[@]} -u ${USER} -d ${USER_HOME} ${action[@]} >> ${actions_logs}
start-stop-daemon -p /var/run/${SERVICE}.pid ${extra_opts[@]} -u ${USER} -d ${USER_HOME} ${action[@]}
echo "$(date): ${ACTION}-ed service '${SERVICE}' for user '${USER}', as '${TYPE}' (${USER_HOME})" >> ${actions_logs}

Save the script and make it executable.

How it works

The script takes the name of itself ($0) and dissects it to extract:

  1. The service name
  2. The user that must run the service
  3. The service type
  4. The action

Based on this information, it will automatically start or stop your services.

Service name: needs to be unique, will be used to create /var/run/<service_name>.pid so that you can check your service status with other tools.

User name: which user shall run the service. Can be omitted (just leave two “–”) and in this case a user with the same name as the service will be used. The user must exist.

Service type: can be podman, service or script:

  1. podman: run podman compose up (or down) as the user
  2. service: source the file $HOME/service_<service>_start and execute COMMAND ARGUMENTS (see example below)
  3. script: will run $HOME/<service> / $HOME/<service>

Example service_<service>_start:

ARGUMENTS=(param1 param2 param3)

Please note that ARGUMENTS should be a bash array.

Adding a container-based service

It's easy, just create the symlink in /etc/local.d.


If you use (and you sohuld) LogRotate to keep your logs sanely rotated and trimmed, add the following /etc/logrotate.d/servicer file: