<commit_before>\" Manpage for immortal.
.\" To correct errors or typos please use https://github.com/immortal/immortal/issues
.TH man 8 "March 2017" "immortal" "immortal man page"
.SH NAME
immortal \- starts and monitor a service
.SH SYNOPSIS
immortal [options] command arguments ...
.SH DESCRIPTION
immortal runs a command or script detached from the controlling terminal as a Unix daemon, it will supervise and restart the service if it has been terminated.
The service can be controlled by querying a Unix socket "immortal.sock", this allows to remotely have full control over the service if required by exposing the socket using a web server like Nginx. see examples section, also immortalctl(8).
.SH OPTIONS
Options start with one dash. Many of the options require an additional value next to them.

-d <dir>
        Change to directory <dir> before starting the command.

-e <dir>
        Set environment variables specified by files within the <dir>.
        For example, if <dir> is /tmp/env and contains 3 files:

        /tmp/env
            |--DEBUG  (contains true)
            |--DBHOST (contains 10.0.0.1)
            `--DBPASS (contains secret)

        An environment var is going to be created for each file, in this case:
            DEBUG=true
            DBHOST=10.0.0.1
            DBPASS=secret

-f <pidfile>
        Follow PID in <pidfile>.
        In some cases it is required to supervise applications that daemonize by default. Normally this kind of applications create a pidfile every time they fork, the one can be used to follow subsequent forks and avoid creating a race condition between the supervisor trying to start again the process and the forks created by the application.

        If using immortalctl(8) the color yellow on the Down column, helps to identify does process that have been forked and that currently are been supervised by the PID on the <pidfile>.
        When the supervised application forks and creates a <pidfile> a log entry (level DAEMON) will be created:

            Watching pid <int> on file <pidfile>

        The follow pid option has better performance on Unix/BSD due the kernel event notification mechanism kqueue(2).

-l <logfile>
        Write stdout/stderr to <logfile>.

-logger <command>
        A command <command> to pipe stdout/stderr from stdin.
        Besides writing logs locally by using the option -l, they can be sent to a remote host or by processed by another tool, for example to write logs locally and send logs remotely using logger this could be used:

            -l /var/log/app.log --logger "logger -h 10.0.0.1 -t app"

-P <pidfile>
        Path to write the supervisor pidfile.

-p <pidfile>
        Path to write the child pidfile.

-s <seconds>
        Seconds (int) <secods> to wait before starting.

-u <user>
        Execute the command on behalf <user>.

-v
        Print version.

-c <service name>.yml
        A configuration file with valid YAML syntax, when using this option, it will overwrite other options, configuration format:

        cmd: <command to execute>
        cwd: <change workding directory> # option -d
        env:                             # option -e
            <key>: <value>
        pid:
            follow: <pidfile>            # option -f
            parent: <pidfile>            # option -P
            child: <pidfile>             # option -p
        log:
            file: <path>                 # option -l
            age: <int>   # seconds
            num: <int>   # int
            size: <int>  # MegaBytes
            timestamp: <bool> # prefix log with timestamp
        logger: <command>                # option -logger
        user: <user>                     # option -u
        wait: <int>                      # option -s
        require:                         # list of services that need to be running before starting
          - foo
          - bar

-ctl /var/run/immortal/<service>
        Path where the supervise directory will be created. This directory is unique per service and is used to manage the service via a Unix socket besides preventing running multiple times the same service by using a lock.

        A supervise directory containing two files:
           lock
           immortal.sock

        When calling immortal from the command line, not by using immortaldir(8) as root, the supervise directory, will be created on a hidden directory named ".immortal" within the $HOME of the user:

        ~/.immortal/<PID>

        This helps to run and supervise the same command multiple times without colliding, useful for testing or for temporary services that will exit when server reboots.

        To keep services up and running on boot time, is better to create a configuration file "run.yml" and use immortaldir(8).
.SH ENVIRONMENT
.TP
.B IMMORTAL_SDIR
This environment variable allows to override the default supervise directory /var/run/immortal, used also by immortalctl(8) and immortaldir(8)
.SH EXAMPLES
Run command and restart it when finishes:

    immortal /bin/sh -c "date && sleep 5 > /tmp/sleep.log"

Run command, restart it when finishes and log output to file:

    immortal -l /tmp/sleep.log /bin/sh -c "date && sleep 5"

Run command, restart it when finishes, log output to file and to external logger:

    immortal -l /tmp/sleep.log -logger "tee /tmp/sleep2.log" /bin/sh -c "date && sleep 5"

Run command, restart it when finishes, log output to file, wait 2 seconds before start:

    immortal -s 2 -l /tmp/sleep.log /bin/sh -c "date && sleep 5"

Run a command, restart it when finishes, log output to file, and follow pid if it forks:

    immortal -l /tmp/x.log -logger "tee /tmp/y.log" -f ./unicorn.pid  bundle exec unicorn -c unicorn.rb

Run a command, restart it when finishes, log output to file and create supervice dir in /tmp/immortal/sleep

    immortal -l /tmp/sleep.log -ctl /tmp/immortal/sleep /bin/sh -c "sleep 5 && date"

    For making immortalctl(8) work using the -ctl <dir> the IMMORTAL_SDIR environment var should be set to /tmp/immortal

Configuration example:

    cmd: bundle exec unicorn -c unicorn.rb
    cwd: /test/unicorn
    env:
        DEBUG: 1
        ENVIROMENT: production
    pid:
        follow: /test/unicorn/unicorn.pid
        parent: /tmp/parent.pid
        child: /tmp/child.pid
    log:
        file: /tmp/app.log
        age: 86400 # seconds
        num: 7     # int
        size: 1    # MegaBytes
    logger: filebeat -c filebeat.yml -v -once
    user: www
    wait: 1

    * Notice that when using the option -u/user, superuser privileges will be required


Nginx example to manage remotely the service:

    immortal -l /tmp/sleep.log -ctl /tmp/immortal/sleep /bin/sh -c "sleep 5 && date"

    Based on your shell set IMMORTAL_SDIR

        setenv IMMORTAL_SDIR /tmp/immortal
<commit_msg>update man page<commit_after>\" Manpage for immortal.
.\" To correct errors or typos please use https://github.com/immortal/immortal/issues
.TH man 8 "September 2017" "immortal" "immortal man page"
.SH NAME
immortal \- starts and monitor a service
.SH SYNOPSIS
immortal [options] command arguments ...
.SH DESCRIPTION
immortal runs a command or script detached from the controlling terminal as a Unix daemon, it will supervise and restart the service if it has been terminated.
The service can be controlled by querying a Unix socket "immortal.sock", this allows to remotely have full control over the service if required by exposing the socket using a web server like Nginx. see examples section, also immortalctl(8).
.SH OPTIONS
Options start with one dash. Many of the options require an additional value next to them.

-d <dir>
        Change to directory <dir> before starting the command.

-e <dir>
        Set environment variables specified by files within the <dir>.
        For example, if <dir> is /tmp/env and contains 3 files:

        /tmp/env
            |--DEBUG  (contains true)
            |--DBHOST (contains 10.0.0.1)
            `--DBPASS (contains secret)

        An environment var is going to be created for each file, in this case:
            DEBUG=true
            DBHOST=10.0.0.1
            DBPASS=<PASSWORD>

-f <pidfile>
        Follow PID in <pidfile>.
        In some cases it is required to supervise applications that daemonize by default. Normally this kind of applications create a pidfile every time they fork, the one can be used to follow subsequent forks and avoid creating a race condition between the supervisor trying to start again the process and the forks created by the application.

        If using immortalctl(8) the color yellow on the Down column, helps to identify does process that have been forked and that currently are been supervised by the PID on the <pidfile>.
        When the supervised application forks and creates a <pidfile> a log entry (level DAEMON) will be created:

            Watching pid <int> on file <pidfile>

        The follow pid option has better performance on Unix/BSD due the kernel event notification mechanism kqueue(2).

-l <logfile>
        Write stdout/stderr to <logfile>.

-logger <command>
        A command <command> to pipe stdout/stderr from stdin.
        Besides writing logs locally by using the option -l, they can be sent to a remote host or by processed by another tool, for example to write logs locally and send logs remotely using logger this could be used:

            -l /var/log/app.log --logger "logger -h 10.0.0.1 -t app"

-P <pidfile>
        Path to write the supervisor pidfile.

-p <pidfile>
        Path to write the child pidfile.

-s <seconds>
        Seconds (int) <secods> to wait before starting.

-u <user>
        Execute the command on behalf <user>.

-v
        Print version.

-c <service name>.yml
        A configuration file with valid YAML syntax, when using this option, it will overwrite other options, configuration format:

        cmd: <command to execute>
        cwd: <change workding directory> # option -d
        env:                             # option -e
            <key>: <value>
        pid:
            follow: <pidfile>            # option -f
            parent: <pidfile>            # option -P
            child: <pidfile>             # option -p
        log:
            file: <path>                 # option -l
            age: <int>   # seconds
            num: <int>   # int
            size: <int>  # MegaBytes
            timestamp: <bool> # prefix log with timestamp
        stderr:
            file: <path>
            age: <int>   # seconds
            num: <int>   # int
            size: <int>  # MegaBytes
            timestamp: <bool> # prefix log with timestamp
        logger: <command>                # option -logger
        user: <user>                     # option -u
        wait: <int>                      # option -s
        require:                         # list of services that need to be running before starting
          - foo
          - bar

-ctl /var/run/immortal/<service>
        Path where the supervise directory will be created. This directory is unique per service and is used to manage the service via a Unix socket besides preventing running multiple times the same service by using a lock.

        A supervise directory containing two files:
           lock
           immortal.sock

        When calling immortal from the command line, not by using immortaldir(8) as root, the supervise directory, will be created on a hidden directory named ".immortal" within the $HOME of the user:

        ~/.immortal/<PID>

        This helps to run and supervise the same command multiple times without colliding, useful for testing or for temporary services that will exit when server reboots.

        To keep services up and running on boot time, is better to create a configuration file "run.yml" and use immortaldir(8).
.SH ENVIRONMENT
.TP
.B IMMORTAL_SDIR
This environment variable allows to override the default supervise directory /var/run/immortal, used also by immortalctl(8) and immortaldir(8)
.SH EXAMPLES
Run command and restart it when finishes:

    immortal /bin/sh -c "date && sleep 5 > /tmp/sleep.log"

Run command, restart it when finishes and log output to file:

    immortal -l /tmp/sleep.log /bin/sh -c "date && sleep 5"

Run command, restart it when finishes, log output to file and to external logger:

    immortal -l /tmp/sleep.log -logger "tee /tmp/sleep2.log" /bin/sh -c "date && sleep 5"

Run command, restart it when finishes, log output to file, wait 2 seconds before start:

    immortal -s 2 -l /tmp/sleep.log /bin/sh -c "date && sleep 5"

Run a command, restart it when finishes, log output to file, and follow pid if it forks:

    immortal -l /tmp/x.log -logger "tee /tmp/y.log" -f ./unicorn.pid  bundle exec unicorn -c unicorn.rb

Run a command, restart it when finishes, log output to file and create supervice dir in /tmp/immortal/sleep

    immortal -l /tmp/sleep.log -ctl /tmp/immortal/sleep /bin/sh -c "sleep 5 && date"

    For making immortalctl(8) work using the -ctl <dir> the IMMORTAL_SDIR environment var should be set to /tmp/immortal

Configuration example:

    cmd: bundle exec unicorn -c unicorn.rb
    cwd: /test/unicorn
    env:
        DEBUG: 1
        ENVIROMENT: production
    pid:
        follow: /test/unicorn/unicorn.pid
        parent: /tmp/parent.pid
        child: /tmp/child.pid
    log:
        file: /tmp/app.log
        age: 86400 # seconds
        num: 7     # int
        size: 1    # MegaBytes
    logger: filebeat -c filebeat.yml -v -once
    user: www
    wait: 1

    * Notice that when using the option -u/user, superuser privileges will be required

In this example, log will write the combined standard output and standard error to file /tmp/app.log, to write and rotate apart the standard error, use the stderr option, example:

    stderr:
        file: /tmp/app-err.log
        age: 86400 # seconds
        num: 7     # int
        size: 1    # MegaBytes

Nginx example to manage remotely the service:

    immortal -l /tmp/sleep.log -ctl /tmp/immortal/sleep /bin/sh -c "sleep 5 && date"

    Based on your shell set IMMORTAL_SDIR

        setenv IMMORTAL_SDIR /tmp/immortal

{'fraction_non_alphanumeric': 0.07049516140425231, 'fraction_numerical': 0.007134279861552589, 'mean_word_length': 2.339938664779429, 'pattern_counts': {'":': 0, '<': 89, '<?xml version=': 0, '>': 91, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2431393', 'n_tokens_mistral': 4090, 'n_tokens_neox': 3775, 'n_words': 1843}