## 8 `Mailfromd` Command Line Syntax ¶

The `mailfromd` binary is started from the command line using the following syntax (brackets indicate optional parts):

    $ mailfromd [options] [asgn] [script]

The meaning of each invocation part is described in the table below:

options

  The command line options (see Command Line Options.).

asgn

  Sendmail macro assignments. These are currently meaningful only with the `--test` option (see test mode), but this may change in the future. Each assignment has the form:

      var=value

  where var is the name of a Sendmail macro and value is the value to be assigned to it.

script

  The file name of the filter script, if other than the default one.

### 8.1 Command Line Options. ¶

#### 8.1.1 Operation Modifiers ¶

`--daemon` ¶

  Run in daemon mode (default).

`--run[=start]` ¶

  Load the script named in the command line and execute the function named start, or ‘`main`’, if start is not given.

  The full invocation syntax for this mode is:

      mailfromd [options] --run[=start \
                [macro=value] [file args...]

  Its parts are:

  options

    Any mailfromd options needed to tune its behavior.

  start

    Start symbol. Defaults to `main`.

  macro=value

    Any number of Sendmail macro definitions. macro is the macro name and value is the value to initialize it to.

  file

    Script file name. If omitted, default script file will be used (see default script file).

  args...

    Command line arguments that will be pased to the start MFL function as parameters.

  The start function must be defined as:

      func start (...) returns number

  See Run Mode, for a detailed discussion of this feature.

`-t[state]` ¶
`--test[=state]`

  Run in test mode. See Testing Filter Scripts. Default state is ‘`envfrom`’. This option implies `--stderr` (see --stderr).

#### 8.1.2 General Settings ¶

`--callout-socket=string` ¶

  Set socket for the default callout server. This is mainly useful together with the `--mtasim` option.

`--echo`
`--echo=file`

  This option controls where the output of the `echo` statement (see The `echo` statement) goes when `mailfromd` is run in test mode, i.e. using the `--test` or `--run` options (see Testing Filter Scripts).

  When used without argument it directs the `echo` output to the standard output stream. If an argument is supplied (second form above), the output goes to the named file. The file will be created if it doesn’t exist. Notice, that the use of ‘`=`’ is compulsory when specifying an argument. A single dash as a filename means standard output, so that `--echo=-` and `--echo` are equivalent.

`--foreground` ¶

  Stay in foreground. When given this option, `mailfromd` will not disconnect itself from the controlling terminal and will run in the foreground.

`-g name` ¶
`--group=name`

  Retain the group name when switching to user privileges. See Starting and Stopping.

  This option complements the `group` configuration statement (see group).

`--include-path=dir` ¶
`-I dir`

  Add the directory dir to the list of directories to be searched for include files (see include search path). This setting affects the `#include` statement (see #include and #include_once) and is used to locate preprocessor setup file (see MFL Preprocessor). If enabled in the configuration (see pass-includes), directories from the include search path will also be added to the preprocessor command line as additional `-I` options.

`--module-path=dir` ¶
`-P dir`

  Add the directory dir to the list of directories searched for MFL module files (see module search path). This setting affects the `require` and `import` MFL statements. See Modules.

`--mailer=url` ¶
`-M url`

  Set the URL of the mailer to use. See Mail Sending Functions.

`--mtasim` ¶

  This option is reserved for use by `mtasim` (see `mtasim` — a testing tool).

`-O[level]` ¶
`--optimize[=level]`

  Set optimization level for code generator. Two levels are implemented: ‘`0`’, meaning no optimization, and ‘`1`’, meaning full optimization.

`-p string` ¶
`--port=string`
`--milter-socket=string`

  Set communication socket. Overrides the `listen` configuration statement, which you are advised to use instead (see listen).

`--pidfile=file` ¶

  Set pidfile name. Overrides the `pidfile` configuration statement, which you are advised to use instead (see pidfile).

`--relayed-domain-file=file` ¶

  Read relayed domains from file. Overrides the `relayed-domain-file` configuration statement (see relayed-domain-file), which you are advised to use instead. See Avoiding Verification Loops, and the description of `relayed` function (see relayed) for more information.

`--resolv-conf-file=file` ¶

  Read resolver settings from file, instead of the default `/etc/resolv.conf`.

`--state-directory=dir` ¶

  Set new program state directory. See Local state directory, for the description of this directory and its purposes. This option overrides the settings of `state-directory` configuration statement, described in state-directory.

`-S ip` ¶
`--source-ip=ip`

  Set source address for TCP connections. Overrides the ‘`source-ip`’ configuration statement, which you are advised to use instead (see source-ip).

`-u name` ¶
`--user name`

  Switch to this user privileges after startup. Overrides the `user` configuration file statement, which you are advised to use instead (see user). Default user is ‘`mail`’.

`-v var=value` ¶
`--variable var=value`

  Assign value to the global variable var. The variable must be declared in your startup script. See overriding initial values, for a detailed discussion of this option.

#### 8.1.3 Preprocessor Options ¶

Following command line options control the preprocessor feature. See MFL Preprocessor, for a detailed discussion of these.

`--no-preprocessor` ¶

  Do not run the preprocessor.

`--preprocessor[=command]` ¶

  If command is supplied, use it as the external preprocessor instead of the default. This overrides the `preprocessor.command` setting (see Preprocessor Configuration).

  If used without arguments, forces the use of the configured preprocessor. This form is intended as a way to manually enable the use of the preprocessor if disabled in the configuration.

`-D name[=value]` ¶
`--define=name[=value]`

  Define a preprocessor symbol name to have a value value. This option is ignored if the `preprocessor.pass-defines` configuration setting is `false`.

`-U name` ¶
`--undefine=name`

  Undefine the preprocessor symbol name. This option is ignored if the `preprocessor.pass-defines` configuration setting is `false`.

`-E` ¶

  Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output.

#### 8.1.4 Timeout Control ¶

See time interval specification, for information on interval format.

`--milter-timeout=interval` ¶

  Set MTA connection timeout. Overrides `milter-timeout` statement in the `mailfromd` configuration file, which you are advised to use instead (see milter-timeout).

#### 8.1.5 Logging and Debugging Options ¶

`--location-column` ¶
`--no-location-column`

  Mention column number in error messages. See location-column. Use `--no-location-column` to disable

`-d string` ¶
`--debug=string`

  Set debugging level. See Logging and Debugging.

`--dump-code` ¶

  Parse and compile the script file and dump the disassembled listing of the produced code to the terminal. See Logging and Debugging.

`--dump-grammar-trace` ¶

  Enable debugging the script file parser. While parsing the file, the detailed dump of the parser states and tokens seen will be output.

`--dump-lex-trace` ¶

  Enable debugging the lexical analyzer. While parsing the script file, the detailed dump of the lexer states and matched rules will be output.

`--dump-macros` ¶

  Show Sendmail macros used in the script file. The macro names are displayed as comma-separated lists, grouped by handler names. See Using `mailfromd` with Sendmail., for a detailed description of this option and its usage.

`--dump-tree` ¶

  Parse and compile the script file and dump the parse tree in a printable form to the terminal.

`--dump-xref` ¶

  Print a cross-reference of variables used in the filter script. See Testing Filter Scripts.

`-E` ¶

  Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output. See MFL Preprocessor.

`--lint` ¶

  Check script file syntax and exit. If the file is OK, return 0 to the shell, otherwise print appropriate messages to stderr and exit with code 78 (‘`configuration error`’).

`--single-process` ¶

  Do not fork sub-processes to serve requests. This option is meant to assist in debugging `mailfromd`. Don’t use it for anything else but for debugging, as it terribly degrades performance!

`--stack-trace` ¶
`--no-stack-trace`

  Add MFL stack trace information to runtime error output. Overrides `stack-trace` configuration statement. Use the `--no-stack-trace` to disable trace information.

  See tracing runtime errors, for more information on this feature.

`--gacopyz-log=level` ¶

  Set desired logging level for `gacopyz` library (see Gacopyz). There are five logging levels. The following table lists them in order of decreasing priority:

  fatal

    Log fatal errors.

  err

    Log error messages.

  warn

    Log warning messages.

  info

    Log informational messages. In particular, this enables printing messages on each subprocess startup and termination, which look like that:

        Apr 28 09:00:11 host mailfromd[9411]: connect
            from 192.168.10.1:50398
        Apr 28 09:00:11 host mailfromd[9411]: finishing
            connection

    This level can be useful for debugging your scripts.

  debug

    Log debugging information.

  proto

    Log Milter protocol interactions. This level prints huge amounts of information, in particular it displays dumps of each Milter packet sent and received.

  Although it is possible to set these levels independently of each other, it is seldom practical. Therefore, the option `--gacopyz-log=level` enables all logging levels from level up. For example, `--gacopyz-log=warn` enables log levels ‘`warn`’, ‘`err`’ and ‘`fatal`’. It is the default. If you need to trace each subprocess startup and shutdown, set `--gacopyz-log=info`. Setting the logging level to ‘`proto`’ can be needed only for `Gacopyz` developers, to debug the protocol.

  See Testing Filter Scripts.

`--logger=mech` ¶

  Set logger mechanism (mech is one of ‘`stderr`’, ‘`syslog`’, ‘`syslog:async`’). See Logging and Debugging.

`--log-facility=facility` ¶

  Output logs to syslog facility.

`--log-tag=string` ¶

  Tag syslog entries with the given string, instead of the program name.

`--source-info` ¶
`--no-source-info`

  Include C source information in debugging messages. This is similar to setting `line-info yes` in the `debug` configuration block (see line-info in GNU Mailutils Manual).

  The `--no-source-info` can be used to cancel the effect of the `line-info yes` configuration statement.

  You do not need this option, unless you are developing or debugging `mailfromd`.

`--syntax-check` ¶

  Synonym for `--lint`.

`--trace` ¶
`--no-trace`

  Enable or disable action tracing. If `--trace` is given, `mailfromd` will log all executed actions. See Logging and Debugging.

`--trace-program[=string]` ¶

  Enable program instruction tracing. With this option `mailfromd` will log execution of every instruction in the compiled filter program. The optional arguments allows to specify a comma-separated list of source code modules for which the tracing is to be enabled, for example `--trace-program=bi_io,bi_db` enables tracing for functions from modules `bi_io.c` and `bi_db.c` (notice, that you need not give file suffixes in string).

  This option is useful for debugging `mailfromd`, but is not advised to use otherwise, since it is very time-costly.

`-X` ¶
`--transcript`
`--no-transcript`

  Enable or disable transcript of the SMTP sessions to the log channel. See Logging and Debugging.

`--syslog` ¶

  Selects default syslog mechanism for diagnostic output.

`--stderr` ¶

  Directs all logging to standard output. Similar to `--logger=stderr`.

`--xref` ¶

  Same as `--dump-xref`. See Logging and Debugging.

#### 8.1.6 Informational Options ¶

`-?`
`--help`

  Give a short help summary.

`--usage`

  Give a short usage message.

`-V`
`--version`

  Print program version.

`--show-defaults` ¶

  Show compilation defaults. See Examining Default Values.

### 8.2 Starting and Stopping ¶

Right after startup, when `mailfromd` has done the operations that require root privileges, it switches to the privileges of the user it is configured to run as (see default user privileges) or the one given in its configuration file (see user). During this process it will drop all supplementary groups and switch to the principal group of that user.

Such limited privileges of the daemon can cause difficulties if your filter script needs to access some files (e.g. `Sendmail` databases) that are not accessible to that user and group. For example, the following fragment using `dbmap` function:

    if dbmap("/etc/mail/aliases.db", $f, 1)
      ...
    fi

will normally fail, because `/etc/mail/aliases.db` is readable only to the root and members of the group ‘`smmsp`’.

In such situations you need to instruct `mailfromd` to retain the privileges of one or several supplementary groups when switching to the user privileges. This is done using `group` statement in the `mailfromd` configuration file (see group). In example above, you need to use the following settings:

    group smmsp;

(The same effect can be achieved with `--group` command line option: `mailfromd --group=smmsp`).

To stop a running instance of `mailfromd` use one of the following signals: `SIGQUIT`, `SIGTERM`, `SIGINT`. All three signals have the same effect: the program cancels handling any pending requests, deinitializes the communication socket (if it is a UNIX socket, the program unlinks it) and exits.

To restart the running `mailfromd` instance, send it `SIGHUP`. For restart to be possible, two conditions must be met: `mailfromd` must be invoked with the full file name, and the configuration file name must be full as well. If either of them is not met, `mailfromd` displays a similar warning message:

    warning: script file is given without full file name
    warning: restart (SIGHUP) will not work

or:

    warning: mailfromd started without full file name
    warning: restart (SIGHUP) will not work

The reaction of `mailfromd` on `SIGHUP` in this case is the same as on the three signals described previously, i.e. cleanup and exit immediately.

The PID of the master instance of `mailfromd` is kept on the pidfile, which is named `mailfromd.pid` and is located in the program state directory. Assuming the default location of the latter, the following command will stop the running instance of the daemon:

    kill -TERM `head -n1 /usr/local/var/mailfromd/mailfromd.pid`

The default pidfile location is shown in the output of `mailfromd --show-defaults` (see Examining Default Values), and can be changed at run time using `pidfile` statement (see pidfile).

To facilitate the use of `mailfromd`, it is shipped with a shell script that can be used to launch it on system startup and shut it down when the system goes down. The script, called `rc.mailfromd`, is located in the directory `/etc` of the distribution. It takes a single argument, specifying the action that should be taken:

start

  Start the program.

stop

  Shut down the program

reload

  Reload the program, by sending it `SIGHUP` signal.

restart

  Shut down the program and start it again.

status

  Display program status. It displays the PID of the master process and its command line, for example:

      $ /etc/rc.d/rc.mailfromd status
      mailformd appears to be running at 26030
      26030 /usr/local/sbin/mailfromd --group smmsp

  If the second line is not displayed, this most probably mean that there is a ‘`stale`’ pidfile, i.e. the one left though the program is not running.

  An empty `rc.mailfromd status` output means that `mailfromd` is not running.

configtest [file]

  Check the script file syntax, report any errors found and exit. If file is given it is checked instead of the default one.

macros [-c] [file]

  Parse the script file (or file, if it is given, extract the names of Sendmail macros it uses and generate corresponding export statements usable in the Sendmail configuration file. By default, `mc` statements are generated. If `-c` (`--cf`) is given, the statements for `sendmail.cf` are output. See the next chapter for the detailed description of this mode.

You can pass any additional arguments to `mailfromd` by editing `ARGS` variable near line 22.

The script is not installed by default. You will have to copy it to the directory where your system start-up scripts reside and ensure it is called during the system startup and shut down. The exact instructions on how to do so depend on the operating system you use and are beyond the scope of this manual.