SvcD class and "svcd" command to run persistent service programmes.
*Latest release 20221228*:
* BREAKING: require "run" subcommand to run a service daemon.
* New "ls" subcommand to report services based on flags.
This provides the features one wants from a daemon
for arbitrary commands providing a service:
* process id (pid) files for both svcd and the service command
* filesystem visible status (command running, service enabled)
via `cs.app.flag`
* command restart if the command exits
* command control (stop, restart, disable) via `cs.app.flag`
* test function to monitor for service viability;
if the test function fails, do not run the service.
This typically monitors something like
network routing (suspend service while laptop offline)
or a ping (suspend ssh tunnel while target does not answer pings).
* signature function to monitor for service restart;
if the signature changes, restart the service.
This typically monitors something like
file contents (restart service on configuration change)
or network routing (restart ssh tunnel on network change)
* callbacks for service command start and end,
for example to display desktop notifications
I use this to run persistent ssh port forwards
and a small collection of other personal services.
I have convenient shell commands to look up service status
and to start/stop/restart services.
See `cs.app.portfwd` which I use to manage my `ssh` tunnels;
it is a single Python programme
running multiple `ssh` commands, each via its own `SvcD` instance.
## Function `callproc(*a, **kw)`
Workalike for subprocess.call, using LockedPopen.
## Function `LockedPopen(*a, **kw)`
Serialise the `Popen` calls.
My long term multithreaded `SvcD` programmes sometimes coredumps.
My working theory is that `Popen`, maybe only on MacOS, is
slightly not multithead safe. This function exists to test
that theory.
## Function `main(argv=None)`
svcd command line.
## Class `SvcD(cs.app.flag.FlaggedMixin)`
A process based service.
*Method `SvcD.__init__(self, *argv, name=None, environ=None, flags=None, group_name=None, pidfile=None, sig_func=None, test_flags=None, test_func=None, test_rate=None, restart_delay=None, once=False, quiet=False, trace=False, on_spawn=None, on_reap=None)`*:
Initialise the SvcD.
Parameters:
* `argv`: command to run as a subprocess.
* `flags`: a cs.app.flag.Flags -like object, default None;
if None the default flags will be used.
* `group_name`: alert group name, default "SVCD " + `name`.
* `pidfile`: path to pid file, default $VARRUN/{name}.pid.
* `sig_func`: signature function to compute a string which
causes a restart if it changes
* `test_flags`: map of {flagname: truthiness} which should
be monitored at test time; truthy flags must be true and
untruthy flags must be false
* `test_func`: test function with must return true if the comannd can run
* `test_rate`: frequency of tests, default SvcD.TEST_RATE
* `restart_delay`: delay before start of an exiting command,
default SvcD.RESTART_DELAY
* `once`: if true, run the command only once
* `quiet`: if true, do not issue alerts
* `trace`: trace actions, default False
* `on_spawn`: to be called after a new subprocess is spawned
* `on_reap`: to be called after a subprocess is reaped
## Class `SvcDCommand(cs.cmdutils.BaseCommand)`
Implementation of `SvcD` command line mode.
Command line usage:
Usage: svcd subcommand [...]
Subcommands:
enable ...
{cmd} enable names
For each name clear the flag {{NAME}}_DISABLE, allowing the matching
svcd to start up its daemon process.
help [-l] [subcommand-names...]
Print the full help for the named subcommands,
or for all subcommands if no names are specified.
-l Long help even if no subcommand-names provided.
ls
List known services.
restart ...
{cmd} restart names...
For each name set the flag {{NAME}}_RESTART, causing the matching
svcd to shut down and then restart its daemon process.
run [-1] [-l] [-L lockname] [-n name] [-t testcmd] [-x] command [args...]
Run a daemon command.
-1 Run command only once.
-l Use lock "svcd-<name>" to prevent multiple instances of this svcd.
-F [!]flag,...
Flags to include in the run test. Flags with a leading
exclaimation point (!) must test false, others true.
-L lockname
Use lock "lockname" to prevent multiple instances of this svcd.
-n name
Specify a name for this svcd.
Also create a subprocess pid file at <function <lambda> at 0x1107773a0>/name.pid for the command.
This also causes svcd to consult the flags {NAME}_OVERRIDE
and {NAME}_DISABLE and {NAME}_RESTART.
-p svcd-pidfile
Specify run pid file instead of default.
-P subp-pidfile
Specify run subprocess pid file instead of default.
-q Quiet. Do not issue alerts.
-s sigcmd
Run the signature shell command "sigcmd" whose output is
used to check for changed circumstances requiring the service
to restart.
-t testcmd
Run the test shell command "testcmd" periodically to
govern whether the command should be active.
-T testrate
Interval between test polls in seconds. Default from SvcD.TEST_RATE
-u username
Run command as the specified username.
-U username
Run test and related commands as the specified username.
-x Trace execution.
stop ...
{cmd} stop names...
For each name set the flag {{NAME}}_STOP, causing the the
montior thread to kill the daemon process and exit.
# Release Log
*Release 20221228*:
* BREAKING: require "run" subcommand to run a service daemon.
* New "ls" subcommand to report services based on flags.
*Release 20210316*:
Serialise the Popen calls to avoid entirely hypothetical subprocess.Popen MT bug that may be making portfwd coredump.
*Release 20190729*:
Get DEVNULL via cs.py3 instead of directly from subprocess.
*Release 20190602.2*:
Another doc tweak.
*Release 20190602.1*:
Improve module documentation formatting.
*Release 20190602*:
* Support alert groups.
* Catch and report exceptions from the monitor signature function.
* Python 2 port fix for DEVNULL.
*Release 20171118*:
Bugfix for su invocation in setuid mode. Improved signature command tracing with -x option.
*Release 20171026*:
Improved logic around signature changes.
*Release 20171025*:
New "-F flag,..." option for svcd. Improve stop logic. Other small fixes.
*Release 20170906*:
Initial PyPI release.
Raw data
{
"_id": null,
"home_page": "https://bitbucket.org/cameron_simpson/css/commits/all",
"name": "cs.app.svcd",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python2,python3",
"author": "Cameron Simpson",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/a4/d0/655af6f6054d77d131058eb52a3d97180e535ec1c01830a575aabe12a0c5/cs.app.svcd-20221228.tar.gz",
"platform": null,
"description": "SvcD class and \"svcd\" command to run persistent service programmes.\n\n*Latest release 20221228*:\n* BREAKING: require \"run\" subcommand to run a service daemon.\n* New \"ls\" subcommand to report services based on flags.\n\nThis provides the features one wants from a daemon\nfor arbitrary commands providing a service:\n\n* process id (pid) files for both svcd and the service command\n* filesystem visible status (command running, service enabled)\n via `cs.app.flag`\n* command restart if the command exits\n* command control (stop, restart, disable) via `cs.app.flag`\n* test function to monitor for service viability;\n if the test function fails, do not run the service.\n This typically monitors something like\n network routing (suspend service while laptop offline)\n or a ping (suspend ssh tunnel while target does not answer pings).\n* signature function to monitor for service restart;\n if the signature changes, restart the service.\n This typically monitors something like\n file contents (restart service on configuration change)\n or network routing (restart ssh tunnel on network change)\n* callbacks for service command start and end,\n for example to display desktop notifications\n\nI use this to run persistent ssh port forwards\nand a small collection of other personal services.\nI have convenient shell commands to look up service status\nand to start/stop/restart services.\n\nSee `cs.app.portfwd` which I use to manage my `ssh` tunnels;\nit is a single Python programme\nrunning multiple `ssh` commands, each via its own `SvcD` instance.\n\n## Function `callproc(*a, **kw)`\n\nWorkalike for subprocess.call, using LockedPopen.\n\n## Function `LockedPopen(*a, **kw)`\n\nSerialise the `Popen` calls.\n\nMy long term multithreaded `SvcD` programmes sometimes coredumps.\nMy working theory is that `Popen`, maybe only on MacOS, is\nslightly not multithead safe. This function exists to test\nthat theory.\n\n## Function `main(argv=None)`\n\nsvcd command line.\n\n## Class `SvcD(cs.app.flag.FlaggedMixin)`\n\nA process based service.\n\n*Method `SvcD.__init__(self, *argv, name=None, environ=None, flags=None, group_name=None, pidfile=None, sig_func=None, test_flags=None, test_func=None, test_rate=None, restart_delay=None, once=False, quiet=False, trace=False, on_spawn=None, on_reap=None)`*:\nInitialise the SvcD.\n\nParameters:\n* `argv`: command to run as a subprocess.\n* `flags`: a cs.app.flag.Flags -like object, default None;\n if None the default flags will be used.\n* `group_name`: alert group name, default \"SVCD \" + `name`.\n* `pidfile`: path to pid file, default $VARRUN/{name}.pid.\n* `sig_func`: signature function to compute a string which\n causes a restart if it changes\n* `test_flags`: map of {flagname: truthiness} which should\n be monitored at test time; truthy flags must be true and\n untruthy flags must be false\n* `test_func`: test function with must return true if the comannd can run\n* `test_rate`: frequency of tests, default SvcD.TEST_RATE\n* `restart_delay`: delay before start of an exiting command,\n default SvcD.RESTART_DELAY\n* `once`: if true, run the command only once\n* `quiet`: if true, do not issue alerts\n* `trace`: trace actions, default False\n* `on_spawn`: to be called after a new subprocess is spawned\n* `on_reap`: to be called after a subprocess is reaped\n\n## Class `SvcDCommand(cs.cmdutils.BaseCommand)`\n\nImplementation of `SvcD` command line mode.\n\nCommand line usage:\n\n Usage: svcd subcommand [...]\n Subcommands:\n enable ...\n {cmd} enable names\n For each name clear the flag {{NAME}}_DISABLE, allowing the matching\n svcd to start up its daemon process.\n help [-l] [subcommand-names...]\n Print the full help for the named subcommands,\n or for all subcommands if no names are specified.\n -l Long help even if no subcommand-names provided.\n ls\n List known services.\n restart ...\n {cmd} restart names...\n For each name set the flag {{NAME}}_RESTART, causing the matching\n svcd to shut down and then restart its daemon process.\n run [-1] [-l] [-L lockname] [-n name] [-t testcmd] [-x] command [args...]\n Run a daemon command.\n -1 Run command only once.\n -l Use lock \"svcd-<name>\" to prevent multiple instances of this svcd.\n -F [!]flag,...\n Flags to include in the run test. Flags with a leading\n exclaimation point (!) must test false, others true.\n -L lockname\n Use lock \"lockname\" to prevent multiple instances of this svcd.\n -n name\n Specify a name for this svcd.\n Also create a subprocess pid file at <function <lambda> at 0x1107773a0>/name.pid for the command.\n This also causes svcd to consult the flags {NAME}_OVERRIDE\n and {NAME}_DISABLE and {NAME}_RESTART.\n -p svcd-pidfile\n Specify run pid file instead of default.\n -P subp-pidfile\n Specify run subprocess pid file instead of default.\n -q Quiet. Do not issue alerts.\n -s sigcmd\n Run the signature shell command \"sigcmd\" whose output is\n used to check for changed circumstances requiring the service\n to restart.\n -t testcmd\n Run the test shell command \"testcmd\" periodically to\n govern whether the command should be active.\n -T testrate\n Interval between test polls in seconds. Default from SvcD.TEST_RATE\n -u username\n Run command as the specified username.\n -U username\n Run test and related commands as the specified username.\n -x Trace execution.\n stop ...\n {cmd} stop names...\n For each name set the flag {{NAME}}_STOP, causing the the\n montior thread to kill the daemon process and exit.\n\n# Release Log\n\n\n\n*Release 20221228*:\n* BREAKING: require \"run\" subcommand to run a service daemon.\n* New \"ls\" subcommand to report services based on flags.\n\n*Release 20210316*:\nSerialise the Popen calls to avoid entirely hypothetical subprocess.Popen MT bug that may be making portfwd coredump.\n\n*Release 20190729*:\nGet DEVNULL via cs.py3 instead of directly from subprocess.\n\n*Release 20190602.2*:\nAnother doc tweak.\n\n*Release 20190602.1*:\nImprove module documentation formatting.\n\n*Release 20190602*:\n* Support alert groups.\n* Catch and report exceptions from the monitor signature function.\n* Python 2 port fix for DEVNULL.\n\n*Release 20171118*:\nBugfix for su invocation in setuid mode. Improved signature command tracing with -x option.\n\n*Release 20171026*:\nImproved logic around signature changes.\n\n*Release 20171025*:\nNew \"-F flag,...\" option for svcd. Improve stop logic. Other small fixes.\n\n*Release 20170906*:\nInitial PyPI release.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "SvcD class and \"svcd\" command to run persistent service programmes.",
"version": "20221228",
"split_keywords": [
"python2",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "504920665109b71d7cfa7ee157a428a6",
"sha256": "7dbedee07796f505a2f51aab41ae29a0812f12ba5050b7474d3ba7f0f166306b"
},
"downloads": -1,
"filename": "cs.app.svcd-20221228-py3-none-any.whl",
"has_sig": false,
"md5_digest": "504920665109b71d7cfa7ee157a428a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10764,
"upload_time": "2022-12-28T01:45:51",
"upload_time_iso_8601": "2022-12-28T01:45:51.943575Z",
"url": "https://files.pythonhosted.org/packages/ec/88/3ef1e1d091c31c9a59199b4905095468ed8d16d3b5354205a9c0998714c6/cs.app.svcd-20221228-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "b531630a48692a9159c159dc8a472445",
"sha256": "f97f53c7b3643a1a374e768f6a76dece8934bfee38ba6a07939ed40e3f34894a"
},
"downloads": -1,
"filename": "cs.app.svcd-20221228.tar.gz",
"has_sig": false,
"md5_digest": "b531630a48692a9159c159dc8a472445",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11121,
"upload_time": "2022-12-28T01:45:54",
"upload_time_iso_8601": "2022-12-28T01:45:54.836670Z",
"url": "https://files.pythonhosted.org/packages/a4/d0/655af6f6054d77d131058eb52a3d97180e535ec1c01830a575aabe12a0c5/cs.app.svcd-20221228.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-28 01:45:54",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "cs.app.svcd"
}
JSON