cpsv(8)

NAME
cpsv - utility to install and manage runit services

SYNOPSIS
cpsv [-f] a <service-directory> [ <service-directory2> ...]
cpsv p <service-directory> [ <service-name> ]
cpsv d <service-directory> [ <service-name> ]
cpsv [-f] s
cpsv l
cpsv i

DESCRIPTION
Use cpsv a or cpsv s to install runscripts from CPSV_SOURCE to CPSV_DEST.
Use cpsv d to inspect runscripts that are already installed in CPSV_DEST.
Use cpsv p to create a named instance from a template, to rename a service or to maintain a partially modified version of a service; templates are installed in CPSV_SOURCE and instances are created in CPSV_DEST.
In a Debian system, by default, CPSV_SOURCE is /usr/share/runit/sv.current and CPSV_DEST is /etc/sv. Debian packages install runscripts in /usr/share/runit/sv and a runitme copy of each relevant service is maintained at /usr/share/runit/sv.current.
When a package installs a runscript in /usr/share/runit/sv/, /etc/sv/ is used to store instances or locally modified copy of that service.

COMMANDS

a   Copy <service> from CPSV_SOURCE into CPSV_DEST, then create symlinks as when the p command is used; more than one <service> name can be given with this command and each <service> directory must exists in CPSV_SOURCE.
    If <service> already exists in CPSV_DEST, cpsv prints a warning, the cp invocation is skipped and the return code is increased by one. The -f option can be used to change this behaviour.

p   Create <CPSV_DEST/service-name> if it does not exists, then populate it with directories and symlinks to <CPSV_SOURCE/service-directory>; <service-directory> must already exist in CPSV_SOURCE; if <service-name> is omitted, <service-directory> is used instead. When <cpsv p> is invoked without root privileges, the <@user> suffix in <service-name>, if any, is stripped.
    <run,check,finish,xchopts,control,.meta,env> and <log/run> are created in <CPSV_DEST/service-name> as symlinks to their conterpart in <CPSV_SOURCE/service-directory>. If a <CPSV_DEST/service-name/.meta/finish> file exists, and a <CPSV_DEST/service-name/finish> file or symlink is not found, cpsv creates a symlink to /lib/runit/finish-exec. If a <CPSV_DEST/service-name/supervise> symlink or directory is not found, cpsv creates one.
    If <CPSV_SOURCE/service-directory/log> is found, <CPSV_DEST/service-name/log> directory is created;
    When a <CPSV_DEST/service-name>/log directory exists: if <service-name>/log/supervise link or directory is not found, cpsv creates one; if <CPSV_SOURCE/service-directory/log/run is found, cpsv creates a <CPSV_DEST/service-name>/log/run symlink to it; otherwise the symlink points to /etc/sv/svlogd/run.
    Files or directories already found in <CPSV_DEST/service-name> are skipped; targets of existing symlinks are not updated.

d   Print the diff between the <service-directory> in CPSV_SOURCE and the <service-name> in CPSV_DEST, then return diff's exit status. <service-directory> must exists in CPSV_SOURCE. If <service-name> is omitted, <service-directory> is used instead. Supervise , conf and wtime are excluded from the diff.

s   Sync CPSV_DEST with CPSV_SOURCE; for each <service> directory in CPSV_SOURCE cpsv will search the system for a systemd or sysv service file with the same name: when it finds one it copies the <service> directory as when the a command is given and goes to the next directory; else cpsv looks for the path written in a <service>/.meta/bin file, and if such path exists in the system then it copies the <service> directory as when the a command is given; otherwise it goes to the next directory.

l   List installed services in CPSV_DEST; the name of each <service> that would be copied with the s command is printed, preceded with character surronded by square brakets;
    [a]: <service>;
     exists in CPSV_SOURCE but not in CPSV_DEST
    [i]: <service>;
     exists both in CPSV_SOURCE and CPSV_DEST, the copy in CPSV_DEST is identical
     to the one created with the a command
    [l]: <service>;
     exists both in CPSV_SOURCE and CPSV_DEST, the copy in CPSV_DEST is different
     from the one created with the a command

i   Install directories and symlinks needed by runit: targets of existing symlinks are never updated this way.
    When run without root privileges, the following directories amd symlinks are installed inside </home/$user/:>
    .runit/sv
    .runit/log
    .runit/supervise
    .runit/runsvdir/default
    .runit/runsvdir/headless
    .service->.runit/runsvdir/current
    .runit/runsvdir/current->.runit/runsvdir/default
    If </home/$user/> directory is not found in the system, cpsv returns 0 immediately.
    Root usage is currently not supported.

OPTIONS

-f  Overwrite <service> files in CPSV_DEST with <service> files in CPSV_SOURCE, no backup is provided. When a <service>/log directory exists, the <service>/log/run file or symlink is replaced with the default one that is created with the p command; supervise directories or symlinks are never overwritten or replaced this way.

ENVIRONMENT

CPSV_DEST
    The environment variable $CPSV_DEST overrides the default directory where services are copied. If omitted or empty, the default is set to /etc/sv when cpsv is run with root privileges, and ~/.runit/sv when cpsv is run without root privileges.

CPSV_SOURCE
    The environment variable $CPSV_SOURCE overrides the default directory from where services are copied. If omitted or empty, the default is set to /usr/share/runit/sv.current. By changing the target of the /usr/share/runit/sv.current symlink it is possible to permanently override CPSV_SOURCE to use a local colletion of runscripts.

FILES
 /etc/sv
 /usr/share/runit/sv.current
 ~/.runit/sv

AUTHOR
Lorenzo Puliti <plorenzo@disroot.org>

SEE ALSO
update-service(8)