\section{Global (Site, User) Config File Reference}
\label{SiteRCReference}

\lstset{language=transcript}

This section defines all legal items and values for cylc site and
user config files. See {\em Site And User Config Files}
(Section~\ref{SiteAndUserConfiguration}) for file locations, intended
usage, and how to generate the files using the
\lstinline=cylc get-site-config= command.

{\em As for suite definitions, Jinja2 expressions can be embedded in
site and user config files to generate the final result parsed by cylc.}
Use of Jinja2 in suite definitions is documented in
Section~\ref{Jinja2}.

\subsection{Top Level Items}

\subsubsection{temporary directory}

A temporary directory is needed by a few cylc commands, and is cleaned
automatically on exit. Leave unset for the default (usually
\lstinline=$TMPDIR=).

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em default:} (none)
\item {\em example:} \lstinline@temporary directory = /tmp/$USER/cylc@
\end{myitemize}

\subsubsection{process pool size}

Number of process pool worker processes used to execute shell commands
(job submission, event handlers, job poll and kill commands).

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} None (number of processor cores on the suite host)
\end{myitemize}

\subsubsection{disable interactive command prompts}

Commands that intervene in running suites can be made to ask for
confirmation before acting. Some find this annoying and ineffective as a
safety measure, however, so command prompts are disabled by default.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} True
\end{myitemize}

\subsubsection{enable run directory housekeeping}

The suite run directory tree is created anew with every suite start
(not restart) but output from the most recent previous runs can be
retained in a rolling archive. Set length to 0 to keep no backups.
{\bf This is incompatible with current Rose suite housekeeping} (see
Section~\ref{SuiteStorageEtc} for more on Rose) so it is disabled by
default, in which case new suite run files will overwrite existing ones
in the same run directory tree. Rarely, this can result in incorrect
polling results due to the presence of old task status files.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} False
\end{myitemize}

\subsubsection{run directory rolling archive length}

The number of old run directory trees to retain if run directory
housekeeping is enabled.
\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 2
\end{myitemize}

\subsubsection{task host select command timeout}

When a task host in a suite is a shell command string, cylc calls the shell to
determine the task host. This call is invoked by the main process, and may
cause the suite to hang while waiting for the command to finish. This setting
sets a timeout for such a command to ensure that the suite can continue.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default: PT10S}
\end{myitemize}

\subsection{[task messaging]}

This section contains configuration items that affect task-to-suite
communications.

\subsubsection[retry interval]{[task messaging] \textrightarrow retry interval}

If a send fails, the messaging code will retry after a configured
delay interval.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:} PT5S
\end{myitemize}

\subsubsection[maximum number of tries]{[task messaging] \textrightarrow maximum number of tries}

If successive sends fail, the messaging code will give up after a
configured number of tries.

\begin{myitemize}
\item {\em type:} integer
\item {\em minimum:} 1
\item {\em default:} 7
\end{myitemize}

\subsubsection[connection timeout]{[task messaging] \textrightarrow connection timeout}

This is the same as the \lstinline=--comms-timeout= option in cylc
commands. Without a timeout remote connections to unresponsive
suites can hang indefinitely (suites suspended with Ctrl-Z for instance).

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:} PT30S
\end{myitemize}

\subsection{[suite logging]}

The suite event log, held under the suite run directory, is maintained
as a rolling archive. Logs are rolled over (backed up and started anew)
when they reach a configurable limit size.

\subsubsection[roll over at start-up]{[suite logging] \textrightarrow roll over at start-up}

If True, a new suite log will be started for a new suite run.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} True
\end{myitemize}

\subsubsection[rolling archive length]{[suite logging] \textrightarrow rolling archive length}

How many rolled logs to retain in the archive.

\begin{myitemize}
\item {\em type:} integer
\item {\em minimum:} 1
\item {\em default:} 5
\end{myitemize}

\subsubsection[maximum size in bytes]{[suite logging] \textrightarrow maximum size in bytes}

Suite event logs are rolled over when they reach this file size.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 1000000
\end{myitemize}

\subsection{[documentation]}

Documentation locations for the \lstinline=cylc doc= command and gcylc
Help menus.

\subsubsection[{[[}files{]]}]{[documentation] \textrightarrow [[files]]}

File locations of documentation held locally on the cylc host server.

\paragraph[html index]{[documentation] \textrightarrow [[files]] \textrightarrow html index }

File location of the main cylc documentation index.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/index.html=
\end{myitemize}

\paragraph[pdf user guide]{[documentation] \textrightarrow [[files]] \textrightarrow pdf user guide }

File location of the cylc User Guide, PDF version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/cug-pdf.pdf=
\end{myitemize}

\paragraph[multi-page html user guide]{[documentation] \textrightarrow [[files]] \textrightarrow multi-page html user guide }

File location of the cylc User Guide, multi-page HTML version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/html/multi/cug-html.html=
\end{myitemize}

\paragraph[single-page html user guide]{[documentation] \textrightarrow [[files]] \textrightarrow single-page html user guide }

File location of the cylc User Guide, single-page HTML version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/html/single/cug-html.html=
\end{myitemize}

\subsubsection[{[[}urls{]]}]{[documentation] \textrightarrow [[urls]]}

Online documentation URLs.

\paragraph[internet homepage]{[documentation] \textrightarrow [[urls]] \textrightarrow internet homepage }

URL of the cylc internet homepage, with links to documentation for the
latest official release.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} http://cylc.github.com/cylc/
\end{myitemize}

\paragraph[local index]{[documentation] \textrightarrow [[urls]] \textrightarrow local index}

Local intranet URL of the main cylc documentation index.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\end{myitemize}

\subsection{[document viewers]}

PDF and HTML viewers can be launched by cylc to view the documentation.

\subsubsection[pdf]{[document viewers] \textrightarrow pdf}

Your preferred PDF viewer program.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} evince
\end{myitemize}

\subsubsection[html]{[document viewers] \textrightarrow html}

Your preferred web browser.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} firefox
\end{myitemize}

\subsection{[editors]}

Choose your favourite text editor for editing suite definitions.

\subsubsection[terminal]{[editors] \textrightarrow terminal}

The editor to be invoked by the cylc command line interface.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=vim=
\item {\em examples:}
    \begin{myitemize}
            \item \lstinline@terminal = emacs -nw@ (emacs non-GUI)
            \item \lstinline@terminal = emacs@ (emacs GUI)
            \item \lstinline@terminal = gvim -f@ (vim GUI)
    \end{myitemize}
\end{myitemize}

\subsubsection[gui]{[editors] \textrightarrow gui}

The editor to be invoked by the cylc GUI.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=gvim -f=
\item {\em examples:}
    \begin{myitemize}
            \item \lstinline@gui = emacs@
            \item \lstinline@gui = xterm -e vim@
    \end{myitemize}
\end{myitemize}


\subsection{[communication]}

This section covers options for network communication between cylc
clients (suite-connecting commands and guis) servers (running suites).
Each suite listens on a dedicated network port, binding on the first
available starting at the configured base port.

By default, the communication method is HTTPS secured with HTTP Digest
Authentication. If the system does not support SSL, you should configure
this section to use HTTP. Cylc will not automatically fall back to HTTP
if HTTPS is not available.

\subsubsection[method]{[communication] \textrightarrow method }

The choice of client-server communication method - currently only HTTPS
and HTTP are supported, although others could be developed and plugged in.
Cylc defaults to HTTPS if this setting is not explicitly configured.

\begin{myitemize}
\item {\em type:} string
\item {\em options:}
    \begin{myitemize}
    \item {\bf https}
    \item {\bf http}
    \end{myitemize}
\item {\em default:} https
\end{myitemize}

\subsubsection[base port]{[communication] \textrightarrow base port }

The first port that cylc is allowed to use.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 43001
\end{myitemize}

\subsubsection[maximum number of ports]{[communication] \textrightarrow maximum number of ports}

This determines the maximum number of suites that can run at once on the
suite host.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 100
\end{myitemize}

\subsubsection[proxies on]{[communication] \textrightarrow proxies on}

Enable or disable proxy servers for HTTPS - disabled by default.

\begin{myitemize}
\item {\em type:} boolean
\item {\em localhost default:} False
\end{myitemize}

\subsubsection[options]{[communication] \textrightarrow options}

Option flags for the communication method. Currently only 'SHA1' is
supported for HTTPS, which alters HTTP Digest Auth to use the SHA1 hash
algorithm rather than the standard MD5. This is more secure but is also
less well supported by third party web clients including web browsers.
You may need to add the 'SHA1' option if you are running on platforms
where MD5 is discouraged (e.g.\  under FIPS).

\begin{myitemize}
\item {\em type:} string\_list
\item {\em default:} \lstinline@[]@
\item {\em options:}
    \begin{myitemize}
        \item {\bf SHA1}
    \end{myitemize}
\end{myitemize}

\subsection{[monitor]}

Configurable settings for the command line \lstinline=cylc monitor= tool.

\subsubsection[monitor]{[monitor] \textrightarrow sort order}

The sort order for tasks in the monitor view.
\begin{myitemize}
    \item {\em type:} string
    \item {\em options:}
    \begin{myitemize}
        \item {\bf alphanumeric}
        \item {\bf definition} -  the order that tasks appear under
            \lstinline=[runtime]= in the suite definition.
    \end{myitemize}
    \item {\em default:} definition
\end{myitemize}

\subsection{[hosts]}

The [hosts] section configures some important host-specific settings for
the suite host (`localhost') and remote task hosts. Note that {\em
remote task behaviour is determined by the site/user config on the
suite host, not on the task host}. Suites can specify task hosts that
are not listed here, in which case local settings will be assumed,
with the local home directory path, if present, replaced by
\lstinline=$HOME= in items that configure directory locations.

\subsubsection[{[[}HOST{]]}]{[hosts] \textrightarrow [[HOST]]}

The default task host is the suite host, {\bf localhost}, with default
values as listed below. Use an explicit \lstinline=[hosts][[localhost]]=
section if you need to override the defaults. Localhost settings are
then also used as defaults for other hosts, with the local home
directory path replaced as described above. This applies to items
omitted from an explicit host section, and to hosts that are not listed
at all in the site and user config files.  Explicit host sections are only
needed if the automatically modified local defaults are not sufficient.

Host section headings can also be {\em regular expressions} to match
multiple hostnames.  Note that the general regular expression wildcard
is `\lstinline=.*=' (zero or more of any character), not
`\lstinline=*='.
Hostname matching regular expressions are used as-is in the Python
\lstinline=re.match()= function. As such they match from the beginning
of the hostname string (as specified in the suite definition) and they
do not have to match through to the end of the string (use the
string-end matching character `\lstinline=$=' in the expression to
force this).

A hierachy of host match expressions from specific to general can be
used because config items are processed in the order specified in the
file.

\begin{myitemize}
\item {\em type:} string (hostname or regular expression)
\item {\em examples:}
\begin{myitemize}
    \item \lstinline@server1.niwa.co.nz@ - explicit host name
    \item  \lstinline@server\d.niwa.co.nz@ - regular expression
\end{myitemize}
\end{myitemize}

\paragraph[run directory]{[hosts] \textrightarrow [[HOST]] \textrightarrow run directory }

The top level of the directory tree that holds suite-specific output logs,
run database, etc.

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em default:} \lstinline=$HOME/cylc-run=
\end{myitemize}

\paragraph[work directory]{[hosts] \textrightarrow [[HOST]] \textrightarrow work directory }
\label{workdirectory}

The top level for suite work and share directories.

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em localhost default:} \lstinline@$HOME/cylc-run@
\end{myitemize}


\paragraph[task communication method]{[hosts] \textrightarrow [[HOST]] \textrightarrow task communication method }
\label{task_comms_method}

The means by which task progress messages are reported back to the running suite.
See above for default polling intervals for the poll method.

\begin{myitemize}
\item {\em type:} string (must be one of the following three options)
\item {\em options:}
    \begin{myitemize}
    \item {\bf default} - direct client-server communication via network ports
    \item {\bf ssh} - use ssh to re-invoke the messaging commands on the suite server
    \item {\bf poll} - the suite polls for the status of tasks (no task messaging)
  \end{myitemize}
\item {\em localhost default:} default
\end{myitemize}

\paragraph[execution polling intervals]{[hosts] \textrightarrow [[HOST]] \textrightarrow execution polling intervals}
\label{execution_polling}

Cylc can poll running jobs to catch problems that prevent task messages
from being sent back to the suite, such as hard job kills, network
outages, or unplanned task host shutdown. Routine polling is done only
for the polling {\em task communication method} (below) unless
suite-specific polling is configured in the suite definition.
A list of interval values can be specified, with the last value used
repeatedly until the task is finished - this allows more frequent
polling near the beginning and end of the anticipated task run time.
Multipliers can be used as shorthand as in the example below.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:}
\item {\em example:} \lstinline@execution polling intervals = 5*PT1M, 10*PT5M, 5*PT1M@
\end{myitemize}


\paragraph[submission polling intervals]{[hosts] \textrightarrow [[HOST]] \textrightarrow submission polling intervals}
\label{submission_polling}

Cylc can also poll submitted jobs to catch problems that prevent the
submitted job from executing at all, such as deletion from an external
batch scheduler queue. Routine polling is done only for the polling {\em
task communication method} (above) unless suite-specific polling
is configured in the suite definition. A list of interval
values can be specified as for execution polling (above) but a single
value is probably sufficient for job submission polling.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:}
\item {\em example:} (see the execution polling example above)
\end{myitemize}

\paragraph[scp command]{[hosts] \textrightarrow [[HOST]] \textrightarrow scp command }

A string for the command used to copy files to a remote host. This is not used
on the suite host unless you run local tasks under another user account. The
value is assumed to be \lstinline=scp= with some initial options or a command
that implements a similar interface to \lstinline=scp=.


\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@scp -oBatchMode=yes -oConnectTimeout=10@
\end{myitemize}

\paragraph[ssh command]{[hosts] \textrightarrow [[HOST]] \textrightarrow ssh command }

A string for the command used to invoke commands on this host. This is not
used on the suite host unless you run local tasks under another user account.
The value is assumed to be \lstinline=ssh= with some initial options or a
command that implements a similar interface to \lstinline=ssh=.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@ssh -oBatchMode=yes -oConnectTimeout=10@
\end{myitemize}

\paragraph[use login shell]{[hosts] \textrightarrow [[HOST]] \textrightarrow use login shell }

Whether to use a login shell or not for remote command invocation. By
default cylc runs remote ssh commands using a login shell:
\begin{lstlisting}
  ssh user@host 'bash --login cylc ...'
\end{lstlisting}
which will source \lstinline=/etc/profile= and
\lstinline=~/.profile= to set up the user environment.  However, for
security reasons some institutions do not allow unattended commands to
start login shells, so you can turn off this behaviour to get:
\begin{lstlisting}
  ssh user@host 'cylc ...'
\end{lstlisting}
which will use the default shell on the remote machine,
sourcing \lstinline=~/.bashrc= (or \lstinline=~/.cshrc=) to set up the
environment.

\begin{myitemize}
\item {\em type:} boolean
\item {\em localhost default:} True
\end{myitemize}

\paragraph[cylc executable]{[hosts] \textrightarrow [[HOST]] \textrightarrow cylc executable }

The \lstinline=cylc= executable on a remote host. Note this should point to the
cylc multi-version wrapper (see~\ref{CUI}) on the host, not
\lstinline=bin/cylc= for a specific installed version.
Specify a full path if \lstinline=cylc= is not in \lstinline=\$PATH= when it is
invoked via \lstinline=ssh= on this host.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@cylc@
\end{myitemize}

\paragraph[global init-script]{[hosts] \textrightarrow [[HOST]] \textrightarrow global init-script }
\label{GlobalInitScript}

If specified, the value of this setting will be inserted to just before the
\lstinline=init-script= section of all job scripts that are to be
submitted to the specified remote host.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@""@
\end{myitemize}

\paragraph[copyable environment variables]{[hosts] \textrightarrow [[HOST]] \textrightarrow copyable environment variables }

A list containing the names of the environment variables that can and/or need
to be copied from the suite server program to a job.

\begin{myitemize}
\item {\em type:} string\_list
\item {\em localhost default:} \lstinline@[]@
\end{myitemize}

\paragraph[retrieve job logs]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs}

Global default for the~\ref{runtime-remote-retrieve-job-logs} setting for the
specified host.

\paragraph[retrieve job logs command]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs command}

If \lstinline@rsync -a@ is unavailable or insufficient to retrieve job logs
from a remote host, you can use this setting to specify a suitable command.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} rsync -a
\end{myitemize}

\paragraph[retrieve job logs max size]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs max size}

Global default for the~\ref{runtime-remote-retrieve-job-logs-max-size} setting for the
specified host.

\paragraph[retrieve job logs retry delays]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs retry delays}

Global default for the~\ref{runtime-remote-retrieve-job-logs-retry-delays}
setting for the specified host.

\paragraph[task event handler retry delays]{[hosts] \textrightarrow [[HOST]] \textrightarrow task event handler retry delays}

Host specific default for the~\ref{runtime-events-handler-retry-delays}
setting.

\paragraph[local tail command template]{[hosts] \textrightarrow [[HOST]] \textrightarrow local tail command template}
\label{local-tail-template}

A template (with \lstinline=%(filename)s= substitution) for the command used to
tail-follow local job logs, used by the gcylc log viewer and
\lstinline=cylc cat-log --tail=.  You are unlikely to need to override this.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline@tail -n +1 -F %(filename)s@
\end{myitemize}

\paragraph[remote tail command template]{[hosts] \textrightarrow [[HOST]] \textrightarrow remote tail command template}
\label{remote-tail-template}

A template (with \lstinline=%(filename)s= substitution) for the command used
to tail-follow remote job logs, used by the gcylc log viewer and
\lstinline=cylc cat-log --tail=.  The remote tail command needs to be told to
die when its parent process exits. You may need to override this command for
task hosts where the default \lstinline=tail= or \lstinline=ps= commands are
not equivalent to the Gnu Linux versions.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline@tail --pid=$(ps h -o ppid $$ | sed -e 's/[[:space:]]//g') -n +1 -F %(filename)s@
\item {\em example:} for AIX hosts:\\
    \lstinline@/gnu/tail --pid=$(ps -o ppid= -p $$ | sed -e 's/[[:space:]]//g') -n +1 -F %(filename)s@
\end{myitemize}

\paragraph[{[[[}batch systems{]]]}]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]]}

Settings for particular batch systems on HOST. In the subsections below, SYSTEM
should be replaced with the cylc batch system handler name that represents the
batch system (see~\ref{RuntimeJobSubMethods}).

\subparagraph[{[[[[}SYSTEM{]]]]}err tailer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow err tailer}
\label{err-tailer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to tail-follow the stderr stream of a running job if SYSTEM does
not use the normal log file location while the job is running.  This setting
overrides~\ref{local-tail-template} and~\ref{remote-tail-template} above.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} For PBS:
    \begin{lstlisting}
[hosts]
    [[ myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                err tailer = qcat -f -e %(job_id)s
                out tailer = qcat -f -o %(job_id)s
                err viewer = qcat -e %(job_id)s
                out viewer = qcat -o %(job_id)s
    \end{lstlisting}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}out tailer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow out tailer}
\label{out-tailer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to tail-follow the stdout stream of a running job if SYSTEM does
not use the normal log file location while the job is running.  This setting
overrides~\ref{local-tail-template} and~\ref{remote-tail-template} above.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}err viewer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow err viewer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to view the stderr stream of a running job if SYSTEM does
not use the normal log file location while the job is running.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}out viewer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow out viewer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to view the stdout stream of a running job if SYSTEM does
not use the normal log file location while the job is running.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}job name length maximum]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow job name length maximum}
\label{JobNameLengthMaximum}

The maximum length for job name acceptable by a batch system on a given host.
Currently, this setting is only meaningful for PBS jobs. For example, PBS 12
or older will fail a job submit if the job name has more than 15 characters,
which is the default setting. If you have PBS 13 or above, you may want to
modify this setting to a larger value.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} (none)
\item {\em example:}  For PBS:
    \begin{lstlisting}
[hosts]
    [[myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                # PBS 13
                job name length maximum = 236
    \end{lstlisting}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}execution time limit polling intervals]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow execution time limit polling intervals}
\label{ExecutionTimeLimitPollingIntervals}

The intervals between polling after a task job (submitted to the relevant batch
system on the relevant host) exceeds its execution time limit. The default
setting is PT1M, PT2M, PT7M. The accumulated times (in minutes) for these
intervals will be roughly 1, 1 + 2 = 3 and 1 + 2 + 7 = 10 after a task job
exceeds its execution time limit.

\begin{myitemize}
    \item {\em type:} Comma-separated list of ISO 8601 duration/interval
        representations, optionally {\em preceded} by multipliers.
    \item {\em default:} PT1M, PT2M, PT7M
    \item {\em example:}
    \begin{lstlisting}
[hosts]
    [[myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                execution time limit polling intervals = 5*PT2M
    \end{lstlisting}
\end{myitemize}

\subsection{[suite host self-identification] }

The suite host's identity must be determined locally by cylc and passed
to running tasks (via \lstinline@$CYLC_SUITE_HOST@) so that task messages
can target the right suite on the right host.

%(TO DO: is it conceivable that different remote task hosts at the same
%site might see the suite host differently? If so we would need to be
%able to override the target in suite definitions.)

\subsubsection[method]{[suite host self-identification] \textrightarrow method }

This item determines how cylc finds the identity of the suite host. For
the default {\em name} method cylc asks the suite host for its host
name. This should resolve on remote task hosts to the IP address of the
suite host; if it doesn't, adjust network settings or use one of the
other methods. For the {\em address} method, cylc attempts to use a
special external ``target address'' to determine the IP address of the
suite host as seen by remote task hosts (in-source documentation in
\lstinline=$CYLC_DIR/lib/cylc/hostuserutil.py= explains how this works).
And finally, as a last resort, you can choose the {\em hardwired} method
and manually specify the host name or IP address of the suite host.

\begin{myitemize}
\item {\em type:} string
\item {\em options:}
\begin{myitemize}
    \item name - self-identified host name
    \item address - automatically determined IP address (requires {\em target}, below)
    \item hardwired - manually specified host name or IP address (requires {\em host}, below)
\end{myitemize}
\item {\em default:} name
\end{myitemize}

\subsubsection[target]{[suite host self-identification] \textrightarrow target }

This item is required for the {\em address} self-identification method.
If your suite host sees the internet, a common address such as
\lstinline@google.com@ will do; otherwise choose a host visible on your
intranet.
\begin{myitemize}
\item {\em type:} string (an inter- or intranet URL visible from the suite host)
\item {\em default:} \lstinline@google.com@
\end{myitemize}


\subsubsection[host]{[suite host self-identification] \textrightarrow host }

Use this item to explicitly set the name or IP address of the suite host
if you have to use the {\em hardwired} self-identification method.
\begin{myitemize}
\item {\em type:} string (host name or IP address)
\item {\em default:} (none)
\end{myitemize}

\subsection{[suite host scanning]}

Utilities such as \lstinline=cylc gsummary= need to scan hosts for
running suites.

\subsubsection[hosts]{[suite host scanning] \textrightarrow hosts }

A list of hosts to scan for running suites.
\begin{myitemize}
\item {\em type:} comma-separated list of host names or IP addresses.
\item {\em default:} localhost
\end{myitemize}

\subsection{[task events]}

Global site/user defaults for~\ref{TaskEventHandling}.

\subsection{[test battery]}

Settings for the automated development tests.

\subsubsection[remote host with shared fs]{[test battery] \textrightarrow remote host with shared fs}

The name of a remote host with shared HOME file system as the host running the
test battery.

\subsubsection[remote host with shared fs]{[test battery] \textrightarrow remote host}

The name of a remote host without shared HOME file system as the host running
the test battery.

\subsubsection[{[[}batch systems{]]}]{[test battery] \textrightarrow [[batch systems]]}

Settings for testing supported batch systems (job submission methods). The
tests for a batch system are only performed if the batch system is available on
the test host or a remote host accessible via SSH from the test host.

\paragraph[{[[[}SYSTEM{]]]}]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]]}

SYSTEM is the name of a supported batch system with automated tests.
This can currently be "loadleveler", "lsf", "pbs", "sge" and/or "slurm".

\subparagraph[host]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow host}

The name of a host where commands for this batch system is available. Use
"localhost" if the batch system is available on the host running the test
battery. Any specified remote host should be accessible via SSH from the host
running the test battery.

\subparagraph[err viewer]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow err viewer}

The command template (with \lstinline=\%(job_id)s= substitution) for testing
the run time stderr viewer functionality for this batch system.

\subparagraph[out viewer]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow out viewer}

The command template (with \lstinline=\%(job_id)s= substitution) for testing
the run time stdout viewer functionality for this batch system.

\subparagraph[{[[[[}directives{]]]]}]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow [[[[directives]]]]}

The minimum set of directives that must be supplied to the batch system on the
site to initiate jobs for the tests.

\subsection{[cylc]}

Default values for entries in the suite.rc [cylc] section.

\subsubsection[UTC mode]{[cylc] \textrightarrow UTC mode}
\label{SiteUTCMode}

Allows you to set a default value for UTC mode in a suite at the site level.
See ~\ref{UTC-mode} for details.

\subsubsection[health check interval]{[cylc] \textrightarrow health check interval}

Site default suite health check interval.
See ~\ref{health-check-interval} for details.

\subsubsection[task event mail interval]{[cylc] \textrightarrow task event mail interval}

Site default task event mail interval.
See ~\ref{task-event-mail-interval} for details.

\subsubsection[{[}events{]}]{[cylc] \textrightarrow [[events]]}
\label{SiteCylcHooks}

You can define site defaults for each of the following options, details
of which can be found under ~\ref{SuiteEventHandling}:

\paragraph[handlers]{[cylc] \textrightarrow [[events]] \textrightarrow handlers}

\paragraph[handler events]{[cylc] \textrightarrow [[events]] \textrightarrow handler events}

\paragraph[startup handler]{[cylc] \textrightarrow [[events]] \textrightarrow startup handler}

\paragraph[shutdown handler]{[cylc] \textrightarrow [[events]] \textrightarrow shutdown handler}

\paragraph[mail events]{[cylc] \textrightarrow [[events]] \textrightarrow mail events}

\paragraph[mail footer]{[cylc] \textrightarrow [[events]] \textrightarrow mail footer}

\paragraph[mail from]{[cylc] \textrightarrow [[events]] \textrightarrow mail from}

\paragraph[mail smtp]{[cylc] \textrightarrow [[events]] \textrightarrow mail smtp}

\paragraph[mail to]{[cylc] \textrightarrow [[events]] \textrightarrow mail to}

\paragraph[timeout handler]{[cylc] \textrightarrow [[events]] \textrightarrow timeout handler}

\paragraph[timeout]{[cylc] \textrightarrow [[events]] \textrightarrow timeout}

\paragraph[abort on timeout]{[cylc] \textrightarrow [[events]] \textrightarrow abort on timeout}

\paragraph[stalled handler]{[cylc] \textrightarrow [[events]] \textrightarrow stalled handler}

\paragraph[abort on stalled]{[cylc] \textrightarrow [[events]] \textrightarrow abort on stalled}

\paragraph[inactivity handler]{[cylc] \textrightarrow [[events]] \textrightarrow inactivity handler}

\paragraph[inactivity]{[cylc] \textrightarrow [[events]] \textrightarrow inactivity}

\paragraph[abort on inactivity]{[cylc] \textrightarrow [[events]] \textrightarrow abort on inactivity}

\subsection{[authentication]}
\label{GlobalAuth}

Authentication of client programs with suite server programs can be configured
here, and overridden in suites if necessary (see~\ref{SuiteAuth}).

The suite-specific passphrase must be installed on a user's account to
authorize full control privileges (see~\ref{tutPassphrases}
and~\ref{ConnectionAuthentication}). In the future we plan to move to a more
traditional user account model so that each authorized user can have their own
password.

\subsubsection[public]{[authentication] \textrightarrow public}

This sets the client privilege level for public access - i.e.\ no suite passphrase
required.

\begin{myitemize}
\item {\em type:} string (must be one of the following options)
\item {\em options:}
    \begin{myitemize}
        \item {\em identity} - only suite and owner names revealed
        \item {\em description} - identity plus suite title and description
        \item {\em state-totals} - identity, description, and task state totals
        \item {\em full-read} - full read-only access for monitor and GUI
        \item {\em shutdown} - full read access plus shutdown, but no other
            control.
    \end{myitemize}
\item {\em default:} state-totals
\end{myitemize}
