cjdroute.conf

package: cjdns

title: cjdroute.conf(5)

summary: Cjdns configuration file

text:
# cjdroute.conf(5)

## NAME
cjdroute.conf - Cjdns configuration file

## DESCRIPTION
The cjdroute.conf file configures the cjdns routing engine, cjdns(8), generally through cjdroute(1).

The configuration is written in a variation of the JSON format that also accepts traditional C-like comments such as single line comments (//) and multiline comments (/* and */). Additionally, unused JSON values found in cjdroute.conf are ignored by cjdns and can be used as a form of JSON-compliant comments.

## CONFIGURATION
"privateKey": "..."

Your node's private key. It should be kept secret because your confidentiality and data integrity depend on it.

"publicKey": "..."

Your node's public key. Based on your private key It is fine for anyone to know this.

"ipv6": "..."

Your node's IPv6 address when it is on the network. It is generated by using the first 16 bytes of a double SHA-512 of your public key. All cjdns IPv6 addresses must begin with "fc" or else they are invalid.

"authorizedPasswords": [...]

An array of passwords that may be used to connect (peer) to your node. "password": "..."

A password which can be used to peer with your node.

"user": "..."

A human-readable string that identifies what password a peer is using on the admin interface. If omitted, the password will be identified by its position within the array (starting from 0)

Example:

"authorizedPasswords":

[

{ "password": "AnExamplePassword", "user": "Bob" },

{ "password": "YetAnotherExample", "user": "Alice" },

{ "password": "j3fus4r3gkhv80xdz1yqc0qvn1p91hr", "user": "Eve" }

]

"admin": {...}

An object which defines where to bind to the admin RPC server as well as the password for the admin RPC server. The two required strings are "bind", which should be in the format "IP:PORT", and "password", which should preferably be a long random string of characters.

"interfaces": {...}

An object that defines which interfaces cjdns will bind to and what peers to connect to. There are two different interfaces, UDPInterface and ETHInterface, both of which are arrays. Within each array there are a variety of different options "bind": "..."

Defines what the interface should bind to. In UDPInterface, the bind is an IP:PORT string, such as "0.0.0.0:12345", while in ETHInterface the bind is a network interface, such as "eth0".

"beacon": Integer

This option is only found in ETHInterface and defines whether auto-connecting beacons should be sent or listened to. This is useful for a zeroconf local network.

0 -- Disabled.

1 -- Accept incoming beacons and try connecting to the sender.

2 -- Accept incoming beacons and broadcast beacons to the local network.

"connectTo": {...}

Defines which nodes cjdns should connect to with the specified interface. Multiple nodes may be placed in a single "connectTo" as long as each are seperated by commas. If a node happens to be offline or become offline during runtime, cjdns will attempt to reconnect at regular intervals. The one difference in this option between UDPInterface and ETHInterface is that UDPInterface connects to an "IP:PORT" while ETHInterface connects to a MAC address. UDPInterface Example:

"connectTo":

{

"1.2.3.4:54321":

{

"login": "login From Your Peer's authorizedPasswords",

"password": "password From Your Peer's authorizedPasswords",

"publicKey": "Your Peer's publicKey.k"

},

"5.6.7.8:46321":

{

"login": "cueball",

"password": "Correct Horse Battery Staple",

"publicKey": "Other Peer's publicKey.k"

}

}

"router": {...}

An object that holds configuration information on the router "interface": {...}

Defines the type of interface used for connecting to the cjdns network. It requires a "type" string, and optionally a "tunDevice" string. The "type" string defines the type of interface used, however only "TUNInterface" is supported at the moment. The "tunDevice" string defines the name of a persistent TUN device to use, which is helpful for starting cjdroute as its own user instead of root.

"ipTunnel": {...}

A system for tunneling ICANN IPv4 and ICANN IPv6 through cjdns. This is using the cjdns switch layer as a VPN carrier. NOTE: Simply editing your configuration file is not sufficient to setting up an ipTunnel gateway. Please read through tunnel/README.md in the cjdns git tree for more information

"allowedConnections": [...]

Nodes allowed to connect to us, specified by their public key, and what IP address(es) to give them. It is fine to only specify one address. Example:

"allowedConnections":

[

{

"publicKey": "f64hfl7c4uxt6krmhPutTheRealAddressOfANodeHere7kfm5m0.k",

"ip4Address": "192.168.1.24",

"ip4Prefix": 24,

"ip6Address": "2001:123:ab::10",

"ip6Prefix": 0

},

{

"publicKey": "ydq8csdk8p8ThisIsJustAnExampleAddresstxuyqdf27hvn2z0.k",

"ip4Address": "192.168.1.25",

"ip4Prefix": 24

}

]

"outgoingConnections": [...]

An array of nodes to connect and ask for IP addresses. Example:

"outgoingConnections":

[

"6743gf5tw80ExampleExampleExampleExamplevlyb23zfnuzv0.k",

"pw9tfmr8pcrExampleExampleExampleExample8rhg1pgwpwf80.k",

"g91lxyxhq0kExampleExampleExampleExample6t0mknuhw75l0.k"

]

"security": [...]

An array that defines what user to change to after startup and whether to exempt the Angel process from this user change. "setuser": "username"

User to switch to after startup, for security purposes. Default value is "nobody".

"exemptAngel": Integer

Whether or not to exempt the Angel process from the user change. The Angel is a small isolated piece of code which exists outside of the core's strict sandbox but does not handle network traffic. This option must be enabled for ipTunnel to automatically set IP addresses for the TUN device. 0 -- False

1 -- True

"logging": {...}

Add or uncomment "logTo":"stdout" to have cjdns log to stdout rather than making logs available via the admin socket

"noBackground": Integer

If set to a non-zero value, cjdns will not fork to the background. Recommended for use in conjunction with "logTo":"stdout".

"dns": {...}

This section is used to configure the dns capabilities being added to cjdns. Unfortunetly, there is no documentation for this DNS section at this time. "keys": [...]

"servers": [...]

"MinSignatures": Integer

## FILES
/etc/cjdroute.conf

A common location for the configuration file.

## SEE ALSO
cjdroute(1), cjdns(8)


clamav-milter.conf

package: clamav

title: clamav-milter.conf(5)

summary: Configuration file for clamav-milter

text:
# clamav-milter.conf(5)

## NAME
clamav-milter.conf - Configuration file for clamav-milter

## DESCRIPTION
clamav-milter.conf contains the configuration options for clamav-milter(8).

## FILE FORMAT
The file consists of comments and options with arguments. Each line which starts with a hash (#) symbol is ignored by the parser. Options and arguments are case sensitive and of the form Option Argument. The arguments are of the following types:

BOOL

Boolean value (yes/no or true/false or 1/0).

STRING

String without blank characters.

SIZE

Size in bytes. You can use 'M' or 'm' modifiers for megabytes and 'K' or 'k' for kilobytes.

NUMBER

Unsigned integer.

## MAIN OPTIONS
Example

If this option is set clamav-milter will not run.

MilterSocket STRING

Define the interface through which we communicate with sendmail. This option is mandatory!

Possible formats are:

[[unix|local]:]/path/to/file - to specify a unix domain socket

inet:port@[hostname|ip-address] - to specify an ipv4 socket

inet6:port@[hostname|ip-address] - to specify an ipv6 socket

Default: unset

MilterSocketGroup STRING

Define the group ownership for the (unix) milter socket.

Default: disabled (the primary group of the user running clamd)

MilterSocketMode STRING

Sets the permissions on the (unix) milter socket to the specified mode.

Default: disabled (obey umask)

FixStaleSocket BOOL

Remove stale socket after unclean shutdown.

Default: yes

User STRING

Run as another user (clamav-milter must be started by root for this option to work)

Default: unset (don´t drop privileges)

ReadTimeout NUMBER

Waiting for data from clamd will timeout after this time (seconds).

Default: 120

Foreground BOOL

Don´t fork into background.

Default: no

Chroot STRING

Chroot to the specified directory. Chrooting is performed just after reading the config file and before dropping privileges.

Default: unset (don´t chroot)

PidFile STRING

Write the daemon's pid to the specified file.

Default: disabled

TemporaryDirectory STRING

Optional path to the global temporary directory.

Default: system specific (usually /tmp or /var/tmp).

## CLAMD OPTIONS
ClamdSocket STRING

Define the clamd socket to connect to for scanning. This option is mandatory! Syntax:

ClamdSocket unix:path

ClamdSocket tcp:host:port

The first syntax specifies a local unix socket (needs an absolute path) e.g.:

ClamdSocket unix:/run/clamav/clamd.sock

The second syntax specifies a tcp local or remote tcp socket: the host can be a hostname or an ip address; the ":port" field is only required for IPv6 addresses, otherwise it defaults to 3310 e.g.:

ClamdSocket tcp:192.168.0.1

This option can be repeated several times with different sockets or even with the same socket: clamd servers will be selected in a round-robin fashion.

Default: no default

## EXCLUSIONS
LocalNet STRING

Messages originating from these hosts/networks will not be scanned. This option takes a host(name)/mask pair in CIRD notation and can be repeated several times. If "/mask" is omitted, a host is assumed. To specify a locally originated, non-smtp, email use the keyword "local"

Default: unset (scan everything regardless of the origin)

AllowList STRING

This option specifies a file which contains a list of basic POSIX regular expressions. Addresses (sent to or from - see below) matching these regexes will not be scanned. Optionally each line can start with the string "From:" or "To:" (note: no whitespace after the colon) indicating if it is, respectively, the sender or recipient that is to be allowed. If the field is missing, "To:" is assumed. Lines starting with #, : or ! are ignored.

Default: unset (no exclusion applied)

SkipAuthenticated STRING

Messages from authenticated SMTP users matching this extended POSIX regular expression (egrep-like) will not be scanned. As an alternative, a file containing a plain (not regex) list of names (one per line) can be specified using the prefix "file:". e.g. SkipAuthenticated file:/etc/good_guys. Note: this is the AUTH login name!

Default: unset (no allowing based on SMTP auth)

MaxFileSize SIZE

Messages larger than this value won´t be scanned. Make sure this value is lower or equal than StreamMaxLength in clamd.conf

Default: 100M

## ACTIONS
The following group of options controls the delivery process under different circumstances. The following actions are available:

- Accept: The message is accepted for delivery

- Reject: Immediately refuse delivery (a 5xx error is returned to the peer)

- Defer: Return a temporary failure message (4xx) to the peer

- Blackhole (not available for OnFail): Like Accept but the message is sent to oblivion

- Quarantine (not available for OnFail): Like Accept but message is quarantined instead of being delivered. NOTE: In Sendmail the quarantine queue can be examined via mailq -qQ. For Postfix this causes the message to be placed on hold.

OnClean STRING

Action to be performed on clean messages (mostly useful for testing)

Default: Accept

OnInfected STRING

Action to be performed on infected messages

Default: Quarantine

OnFail STRING

Action to be performed on error conditions (this includes failure to allocate data structures, no scanners available, network timeouts, unknown scanner replies and the like)

Default: Defer

RejectMsg STRING

This option allows you to set a specific rejection reason for infected messages and it´s therefore only useful together with "OnInfected Reject". The string "%v", if present, will be replaced with the virus name.

Default: MTA specific

AddHeader STRING

If this option is set to "Replace" (or "Yes"), an "X-Virus-Scanned" and an "X-Virus-Status" headers will be attached to each processed message, possibly replacing existing headers. If it is set to Add, the X-Virus headers are added possibly on top of the existing ones. Note that while "Replace" can potentially break DKIM signatures, "Add" may confuse procmail and similar filters.

Default: no

ReportHostname STRING

When AddHeader is in use, this option allows you to set the reported hostname. This may be desirable in order to avoid leaking internal names. If unset the real machine name is used.

Default: disabled

VirusAction STRING

Execute a command (possibly searching PATH) when an infected message is found. The following parameters are passed to the invoked program in this order: virus name, queue id, sender, destination, subject, message id, message date. Note #1: this requires MTA macroes to be available (see LogInfected below). Note #2: the process is invoked in the context of clamav-milter. Note #3: clamav-milter will wait for the process to exit. Be quick or fork to avoid unnecessary delays in email delivery.

Default: disabled

## LOGGING OPTIONS
LogFile STRING

Enable logging to selected file.

Default: no

LogFileUnlock BOOL

Disable a system lock that protects against running clamd with the same configuration file multiple times.

Default: no

LogFileMaxSize SIZE

Limit the size of the log file. The logger will be automatically disabled if the file is greater than SIZE. Value of 0 disables the limit.

Default: 1M

LogTime BOOL

Log time for each message.

Default: no

LogSyslog BOOL

Use system logger (can work together with LogFile).

Default: no

LogFacility STRING

Specify the type of syslog messages - please refer to 'man syslog' for facility names.

Default: LOG_LOCAL6

LogVerbose BOOL

Enable verbose logging.

Default: no

LogInfected STRING

This option allows you to tune what is logged when a message is infected. Possible values are Off (the default - nothing is logged), Basic (minimal info logged), Full (verbose info logged)

Note: For this to work properly in sendmail, make sure the msg_id, mail_addr, rcpt_addr and i macroes are available in eom. In other words add a line like: Milter.macros.eom={msg_id}, {mail_addr}, {rcpt_addr}, i to your .cf file. Alternatively use the macro: define(`confMILTER_MACROS_EOM', `{msg_id}, {mail_addr}, {rcpt_addr}, i')

Postfix should be working fine with the default settings.

Default: disabled

LogClean STRING

This option allows you to tune what is logged when no threat is found in a scanned message.

See LogInfected for possible values and caveats.

Useful in debugging but drastically increases the log size.

Default: disabled

SupportMultipleRecipients BOOL

This option affects the behaviour of LogInfected, LogClean and VirusAction when a message with multiple recipients is scanned:

If SupportMultipleRecipients is off (the default) then one single log entry is generated for the message and, in case the message is determined to be malicious, the command indicated by VirusAction is executed just once. In both cases only the last recipient is reported.

If SupportMultipleRecipients is on then one line is logged for each recipient and the command indicated by VirusAction is also executed once for each recipient.

Note: although it's probably a good idea to enable this option, the default value is currently set to off for legacy reasons.

Default: no

## NOTES
All options expressing a size are limited to max 4GB. Values in excess will be reset to the maximum.

## FILES
/etc/clamav/clamav-milter.conf

## AUTHOR
aCaB <acab@clamav.net>

## SEE ALSO
clamav-milter(8), clamd(8), clamd.conf(5)


clamd.conf

title: clamd.conf(5)

text:
# clamd.conf(5)

## NAME
clamd.conf - Configuration file for Clam AntiVirus Daemon

## DESCRIPTION
clamd.conf configures the Clam AntiVirus daemon, clamd(8).

## FILE FORMAT
The file consists of comments and options with arguments. Each line which starts with a hash (#) symbol is ignored by the parser. Options and arguments are case sensitive and of the form Option Argument. The arguments are of the following types:

BOOL

Boolean value (yes/no or true/false or 1/0).

STRING

String without blank characters.

SIZE

Size in bytes. You can use 'M' or 'm' modifiers for megabytes and 'K' or 'k' for kilobytes. To specify the size in bytes just don't use modifiers.

NUMBER

Unsigned integer.

## DIRECTIVES
When some option is not used (commented out or not included in the configuration file at all) clamd takes a default action.

Example

If this option is set clamd will not run.

LogFile STRING

Save all reports to a log file.

Default: disabled

LogFileUnlock BOOL

By default the log file is locked for writing and only a single daemon process can write to it. This option disables the lock.

Default: no

LogFileMaxSize SIZE

Maximum size of the log file.

Value of 0 disables the limit.

Default: 1048576

LogTime BOOL

Log time for each message.

Default: no

LogClean BOOL

Log all clean files.

Useful in debugging but drastically increases the log size.

Default: no

LogSyslog BOOL

Use the system logger (can work together with LogFile).

Default: no

LogFacility STRING

Type of syslog messages

Please refer to 'man syslog' for facility names.

Default: LOG_LOCAL6

LogVerbose BOOL

Enable verbose logging.

Default: no

LogRotate BOOL

Rotate log file. Requires LogFileMaxSize option set prior to this option.

Default: no

ExtendedDetectionInfo BOOL

Log additional information about the infected file, such as its size and hash, together with the virus name.

Default: no

PidFile STRING

Write the daemon's pid to the specified file.

Default: disabled

TemporaryDirectory STRING

This option allows you to change the default temporary directory.

Default: system specific (usually /tmp or /var/tmp).

DatabaseDirectory STRING

This option allows you to change the default database directory. If you enable it, please make sure it points to the same directory in both clamd and freshclam.

Default: defined at configuration (/usr/local/share/clamav)

OfficialDatabaseOnly BOOL

Only load the official signatures published by the ClamAV project.

Default: no

FailIfCvdOlderThan NUMBER

Return with a nonzero error code if the virus database is older than the specified number of days.

Default: -1

LocalSocket STRING

Path to a local (Unix) socket the daemon will listen on.

Default: disabled

LocalSocketGroup STRING

Sets the group ownership on the unix socket.

Default: the primary group of the user running clamd

LocalSocketMode STRING

Sets the permissions on the unix socket to the specified mode.

Default: socket is world readable and writable

FixStaleSocket BOOL

Remove stale socket after unclean shutdown.

Default: yes

TCPSocket NUMBER

TCP port number the daemon will listen on.

Default: disabled

TCPAddr STRING

By default clamd binds to INADDR_ANY.

This option allows you to restrict the TCP address and provide some degree of protection from the outside world. This option can be specified multiple times in order to listen on multiple IPs. IPv6 is now supported.

Default: disabled

MaxConnectionQueueLength NUMBER

Maximum length the queue of pending connections may grow to.

Default: 200

StreamMaxLength SIZE

Close the STREAM session when the data size limit is exceeded.

The value should match your MTA's limit for the maximum attachment size.

Default: 100M

StreamMinPort NUMBER

The STREAM command uses an FTP-like protocol.

This option sets the lower boundary for the port range.

Default: 1024

StreamMaxPort NUMBER

This option sets the upper boundary for the port range.

Default: 2048

MaxThreads NUMBER

Maximum number of threads running at the same time.

Default: 10

ReadTimeout NUMBER

This option specifies the time (in seconds) after which clamd should timeout if a client doesn't provide any data.

Default: 120

CommandReadTimeout NUMBER

This option specifies the time (in seconds) after which clamd should timeout if a client doesn't provide any initial command after connecting. The default is set to 30 to avoid timeouts with TCP sockets when processing large messages. If using a Unix socket, the value can be changed to 5. Note: the timeout for subsequents commands, and/or data chunks is specified by ReadTimeout.

Default: 30

SendBufTimeout NUMBER

This option specifies how long to wait (in milliseconds) if the send buffer is full. Keep this value low to prevent clamd hanging.

Default: 500

MaxQueue NUMBER

Maximum number of queued items (including those being processed by MaxThreads threads). It is recommended to have this value at least twice MaxThreads if possible.

WARNING: you shouldn't increase this too much to avoid running out of file descriptors, the following condition should hold: MaxThreads*MaxRecursion + MaxQueue - MaxThreads + 6 < RLIMIT_NOFILE. RLIMIT_NOFILE is the maximum number of open file descriptors (usually 1024), set by ulimit -n.

Default: 100

IdleTimeout NUMBER

This option specifies how long (in seconds) the process should wait for a new job.

Default: 30

ExcludePath REGEX

Don't scan files and directories matching REGEX. This directive can be used multiple times.

Default: disabled

MaxDirectoryRecursion NUMBER

Maximum depth directories are scanned at.

Default: 15

FollowDirectorySymlinks BOOL

Follow directory symlinks.

Default: no

CrossFilesystems BOOL

Scan files and directories on other filesystems.

Default: yes

FollowFileSymlinks BOOL

Follow regular file symlinks.

Default: no

SelfCheck NUMBER

This option specifies the time intervals (in seconds) in which clamd should perform a database check.

Default: 600

ConcurrentDatabaseReload BOOL

Enable non-blocking (multi-threaded/concurrent) database reloads. This feature will temporarily load a second scanning engine while scanning continues using the first engine. Once loaded, the new engine takes over. The old engine is removed as soon as all scans using the old engine have completed. This feature requires more RAM, so this option is provided in case users are willing to block scans during reload in exchange for lower RAM requirements.

Default: yes

VirusEvent COMMAND

Execute a command when virus is found. Use the following environment variables to identify the file and virus names: - $CLAM_VIRUSEVENT_FILENAME - $CLAM_VIRUSEVENT_VIRUSNAME In the command string, '%v' will also be replaced with the virus name. Note: The '%f' filename format character has been disabled and will no longer be replaced with the file name, due to command injection security concerns. Use the 'CLAM_VIRUSEVENT_FILENAME' environment variable instead. For the same reason, you should NOT use the environment variables in the command directly, but should use it carefully from your executed script.

Default: disabled

ExitOnOOM BOOL

Stop daemon when libclamav reports out of memory condition.

Default: no

AllowAllMatchScan BOOL

Permit use of the ALLMATCHSCAN command.

Default: yes

Foreground BOOL

Don't fork into background.

Default: no

Debug BOOL

Enable debug messages from libclamav.

Default: no

LeaveTemporaryFiles BOOL

Do not remove temporary files (for debugging purpose).

Default: no

GenerateMetadataJson BOOL

Record metadata about the file being scanned. Scan metadata is useful for file analysis purposes and for debugging scan behavior. The JSON metadata will be printed after the scan is complete if Debug is enabled. A metadata.json file will be written to the scan temp directory if LeaveTemporaryFiles is enabled.

Default: no

User STRING

Run the daemon as a specified user (the process must be started by root).

Default: disabled

Bytecode BOOL

With this option enabled ClamAV will load bytecode from the database. It is highly recommended you keep this option turned on, otherwise you may miss detections for many new viruses.

Default: yes

BytecodeSecurity STRING

Set bytecode security level.

Possible values:

TrustSigned - trust bytecode loaded from signed .c[lv]d files and insert runtime safety checks for bytecode loaded from other sources,

Paranoid - don't trust any bytecode, insert runtime checks for all.

Recommended: TrustSigned, because bytecode in .cvd files already has these checks.

Default: TrustSigned

BytecodeTimeout NUMBER

Set bytecode timeout in milliseconds.

Default: 10000

BytecodeUnsigned BOOL

Allow loading bytecode from outside digitally signed .c[lv]d files. **Caution**: You should NEVER run bytecode signatures from untrusted sources. Doing so may result in arbitrary code execution.

Default: no

BytecodeMode STRING

Set bytecode execution mode.

Possible values:

Auto - automatically choose JIT if possible, fallback to interpreter

ForceJIT - always choose JIT, fail if not possible

ForceInterpreter - always choose interpreter

Test - run with both JIT and interpreter and compare results. Make all failures fatal.

Default: Auto

DetectPUA BOOL

Detect Possibly Unwanted Applications.

Default: No

ExcludePUA CATEGORY

Exclude a specific PUA category. This directive can be used multiple times. See https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA categories.

Default: disabled

IncludePUA CATEGORY

Only include a specific PUA category. This directive can be used multiple times. See https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA categories.

Default: disabled

HeuristicAlerts BOOL

In some cases (eg. complex malware, exploits in graphic files, and others), ClamAV uses special algorithms to provide accurate detection. This option controls the algorithmic detection.

Default: yes

HeuristicScanPrecedence BOOL

Allow heuristic match to take precedence. When enabled, if a heuristic scan (such as phishingScan) detects a possible virus/phishing it will stop scanning immediately. Recommended, saves CPU scan-time. When disabled, virus/phishing detected by heuristic scans will be reported only at the end of a scan. If an archive contains both a heuristically detected virus/phishing, and a real malware, the real malware will be reported. Keep this disabled if you intend to handle "*.Heuristics.*" viruses differently from "real" malware. If a non-heuristically-detected virus (signature-based) is found first, the scan is interrupted immediately, regardless of this config option.

Default: no

ScanPE BOOL

PE stands for Portable Executable - it's an executable file format used in all 32 and 64-bit versions of Windows operating systems. This option allows ClamAV to perform a deeper analysis of executable files and it's also required for decompression of popular executable packers such as UPX.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanELF BOOL

Executable and Linking Format is a standard format for UN*X executables. This option allows you to control the scanning of ELF files.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanMail BOOL

Enable scanning of mail files.

If you turn off this option, the original files will still be scanned, but without parsing individual messages/attachments.

Default: yes

ScanPartialMessages BOOL

Scan RFC1341 messages split over many emails. You will need to periodically clean up $TemporaryDirectory/clamav-partial directory. WARNING: This option may open your system to a DoS attack. Never use it on loaded servers.

Default: no

PhishingSignatures BOOL

Enable email signature-based phishing detection.

Default: yes

PhishingScanURLs BOOL

Enable URL signature-based phishing detection (Heuristics.Phishing.Email.*)

Default: yes

StructuredDataDetection BOOL

Enable the DLP module.

Default: no

StructuredMinCreditCardCount NUMBER

This option sets the lowest number of Credit Card numbers found in a file to generate a detect.

Default: 3

StructuredCCOnly BOOL

With this option enabled the DLP module will search for valid Credit Card0umbers only. Debit and Private Label cards will not be searched.

Default: No

StructuredMinSSNCount NUMBER

This option sets the lowest number of Social Security Numbers found in a file to generate a detect.

Default: 3

StructuredSSNFormatNormal BOOL

With this option enabled the DLP module will search for valid SSNs formatted as xxx-yy-zzzz.

Default: Yes

StructuredSSNFormatStripped BOOL

With this option enabled the DLP module will search for valid SSNs formatted as xxxyyzzzz.

Default: No

ScanHTML BOOL

Perform HTML/JavaScript/ScriptEncoder normalisation and decryption.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanOLE2 BOOL

This option enables scanning of OLE2 files, such as Microsoft Office documents and .msi files.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanPDF BOOL

This option enables scanning within PDF files.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanSWF BOOL

This option enables scanning within SWF files.

If you turn off this option, the original files will still be scanned, but without decoding and additional processing.

Default: yes

ScanXMLDOCS BOOL

This option enables scanning xml-based document files supported by libclamav.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanHWP3 BOOL

This option enables scanning HWP3 files.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanOneNote BOOL

This option enables scanning OneNote files.

If you turn off this option, the original files will still be scanned, but without additional processing.

Default: yes

ScanArchive BOOL

Scan within archives and compressed files.

If you turn off this option, the original files will still be scanned, but without unpacking and additional processing.

Default: yes

ScanImage BOOL

This option enables scanning of image (graphics).

If you turn off this option, the original files will still be scanned, but without unpacking and additional processing.

Default: yes

ScanImageFuzzyHash BOOL

This option enables detection by calculating a fuzzy hash of image (graphics) files. Signatures using image fuzzy hashes typically match files and documents by identifying images embedded or attached to those files.

If you turn off this option, then some files may no longer be detected.

Default: yes

AlertBrokenExecutables BOOL

Alert on broken executable files (PE & ELF).

Default: no

AlertBrokenMedia BOOL

Alert on broken graphics files (JPEG, TIFF, PNG, GIF).

Default: no

AlertEncrypted BOOL

Alert on encrypted archives and documents (encrypted .zip, .7zip, .rar, .pdf).

Default: no

AlertEncryptedArchive BOOL

Alert on encrypted archives (encrypted .zip, .7zip, .rar).

Default: no

AlertEncryptedDoc BOOL

Alert on encrypted documents (encrypted .pdf).

Default: no

AlertOLE2Macros BOOL

Alert on OLE2 files containing VBA macros (Heuristics.OLE2.ContainsMacros).

Default: no

AlertExceedsMax BOOL

When AlertExceedsMax is set, files exceeding the MaxFileSize, MaxScanSize, or MaxRecursion limit will be flagged with the virus name starting with "Heuristics.Limits.Exceeded".

Default: no

AlertPhishingSSLMismatch BOOL

Alert on emails containing SSL mismatches in URLs (might lead to false positives!).

Default: no

AlertPhishingCloak BOOL

Alert on emails containing cloaked URLs (might lead to some false positives).

Default: no

AlertPartitionIntersection BOOL

Alert on raw DMG image files containing partition intersections.

Default: no

DisableCache

This option allows you to disable the caching feature of the engine.

By default, the engine will store an MD5 in a cache of any files that are not flagged as virus or that hit limits checks. Warning: Disabling the cache will have a negative performance impact on large scans.

Default: no

CacheSize

This option allows you to set the number of entries the cache can store. The value should be a square number or will be rounded up to the nearest square number.

Default: 65536

ForceToDisk

This option causes memory or nested map scans to dump the content to disk.

If you turn on this option, more data is written to disk and is available when the leave-temps option is enabled at the cost of more disk writes.

Default: no

MaxScanTime SIZE

This option sets the maximum amount of time a scan may take to complete. The value is in milliseconds. The value of 0 disables the limit. WARNING: disabling this limit or setting it too high may result allow scanning of certain files to lock up the scanning process/threads resulting in a Denial of Service.

Default: 120000

MaxScanSize SIZE

Sets the maximum amount of data to be scanned for each input file. Archives and other containers are recursively extracted and scanned up to this value. The size of an archive plus the sum of the sizes of all files within archive count toward the scan size. For example, a 1M uncompressed archive containing a single 1M inner file counts as 2M toward the max scan size. Warning: disabling this limit or setting it too high may result in severe damage to the system.

Default: 400M

MaxFileSize SIZE

Files larger than this limit won't be scanned. Affects the input file itself as well as files contained inside it (when the input file is an archive, a document or some other kind of container). Warning: disabling this limit or setting it too high may result in severe damage to the system. Technical design limitations prevent ClamAV from scanning files greater than 2 GB at this time.

Default: 100M

MaxRecursion NUMBER

Nested archives are scanned recursively, e.g. if a Zip archive contains a RAR file, all files within it will also be scanned. This options specifies how deeply the process should be continued. Warning: setting this limit too high may result in severe damage to the system.

Default: 17

MaxFiles NUMBER

Number of files to be scanned within an archive, a document, or any other kind of container. Warning: disabling this limit or setting it too high may result in severe damage to the system.

Default: 10000

MaxEmbeddedPE SIZE

This option sets the maximum size of a file to check for embedded PE.

Files larger than this value will skip the additional analysis step.

Negative values are not allowed.

Default: 40M

MaxHTMLNormalize SIZE

This option sets the maximum size of a HTML file to normalize.

HTML files larger than this value will not be normalized or scanned.

Negative values are not allowed.

Default: 40M

MaxHTMLNoTags SIZE

This option sets the maximum size of a normalized HTML file to scan.

HTML files larger than this value after normalization will not be scanned.

Negative values are not allowed.

Default: 8M

MaxScriptNormalize SIZE

This option sets the maximum size of a script file to normalize.

Script content larger than this value will not be normalized or scanned.

Negative values are not allowed.

Default: 20M

MaxZipTypeRcg SIZE

This option sets the maximum size of a ZIP file to reanalyze type recognition.

ZIP files larger than this value will skip the step to potentially reanalyze as PE.

Negative values are not allowed.

WARNING: setting this limit too high may result in severe damage or impact performance.

Default: 1M

MaxPartitions SIZE

This option sets the maximum number of partitions of a raw disk image to be scanned.

Raw disk images with more partitions than this value will have up to the value partitions scanned.

Negative values are not allowed.

WARNING: setting this limit too high may result in severe damage or impact performance.

Default: 50

MaxIconsPE SIZE

This option sets the maximum number of icons within a PE to be scanned.

PE files with more icons than this value will have up to the value number icons scanned.

Negative values are not allowed.

WARNING: setting this limit too high may result in severe damage or impact performance.

Default: 100

MaxRecHWP3 NUMBER

This option sets the maximum recursive calls to HWP3 parsing function.

HWP3 files using more than this limit will be terminated and alert the user.

Scans will be unable to scan any HWP3 attachments if the recursive limit is reached.

Negative values are not allowed.

WARNING: setting this limit too high may result in severe damage or impact performance.

Default: 16

PCREMatchLimit NUMBER

This option sets the maximum calls to the PCRE match function during an instance of regex matching.

Instances using more than this limit will be terminated and alert the user but the scan will continue.

For more information on match_limit, see the PCRE documentation.

Negative values are not allowed.

WARNING: setting this limit too high may severely impact performance.

Default: 10000

PCRERecMatchLimit NUMBER

This option sets the maximum recursive calls to the PCRE match function during an instance of regex matching.

Instances using more than this limit will be terminated and alert the user but the scan will continue.

For more information on match_limit_recursion, see the PCRE documentation.

Negative values are not allowed and values > PCREMatchLimit are superfluous.

WARNING: setting this limit too high may severely impact performance.

Default: 2000

PCREMaxFileSize SIZE

This option sets the maximum filesize for which PCRE subsigs will be executed.

Files exceeding this limit will not have PCRE subsigs executed unless a subsig is encompassed to a smaller buffer.

Negative values are not allowed.

Setting this value to zero disables the limit.

WARNING: setting this limit too high or disabling it may severely impact performance.

Default: 100M

OnAccessIncludePath STRING

This option specifies a directory (including all files and directories inside it), which should be scanned on access. This option can be used multiple times.

Default: disabled

OnAccessExcludePath STRING

This option allows excluding directories from on-access scanning. It can be used multiple times.

Default: disabled

OnAccessExcludeRootUID BOOL

With this option you can exclude the root UID (0). Processes run under root will be able to access all files without triggering scans or permission denied events.

Note that if clamd cannot check the uid of the process that generated an on-access scan event (e.g., because OnAccessPrevention was not enabled, and the process already exited), clamd will perform a scan. Thus, setting OnAccessExcludeRootUID is not guaranteed to prevent every access by the root user from triggering a scan (unless OnAccessPrevention is enabled).

Default: no

OnAccessExcludeUID NUMBER

With this option you can exclude specific UIDs. Processes with these UIDs will be able to access all files without triggering scans or permission denied events.

This option can be used multiple times (one per line).

Note: using a value of 0 on any line will disable this option entirely. To exclude the root UID (0) please enable the OnAccessExcludeRootUID option.

Also note that if clamd cannot check the uid of the process that generated an on-access scan event (e.g., because OnAccessPrevention was not enabled, and the process already exited), clamd will perform a scan. Thus, setting OnAccessExcludeUID is not guaranteed to prevent every access by the specified uid from triggering a scan (unless OnAccessPrevention is enabled).

Default: disabled

OnAccessExcludeUname STRING

This option allows exclusions via user names when using the on-access scanning client. It can be used multiple times, and has the same potential race condition limitations of the OnAccessExcludeUID option.

Default: disabled

OnAccessMaxFileSize SIZE

Files larger than this value will not be scanned in on access.

Default: 5M

OnAccessMaxThreads NUMBER

Max number of scanning threads to allocate to the OnAccess thread pool at startup. These threads are the ones responsible for creating a connection with the daemon and kicking off scanning after an event has been processed. To prevent clamonacc from consuming all clamd's resources keep this lower than clamd's max threads.

Default: 5

OnAccessCurlTimeout NUMBER

Max amount of time (in milliseconds) that the OnAccess client should spend for every connect, send, and receive attempt when communicating with clamd via curl.

Default: 5000 (5 seconds)

OnAccessMountPath STRING

Specifies a mount point (including all files and directories under it), which should be scanned on access. This option can be used multiple times.

Default: disabled

OnAccessDisableDDD BOOL

Disables the dynamic directory determination system which allows for recursively watching include paths.

Default: no

OnAccessPrevention BOOL

Enables fanotify blocking when malicious files are found.

Default: disabled

OnAccessRetryAttempts NUMBER

Number of times the OnAccess client will retry a failed scan due to connection problems (or other issues).

Default: 0

OnAccessDenyOnError BOOL

When using prevention, if this option is turned on, any errors that occur during scanning will result in the event attempt being denied. This could potentially lead to unwanted system behaviour with certain configurations, so the client defaults this to off and prefers allowing access events in case of scan or connection error.

Default: no

OnAccessExtraScanning BOOL

Toggles extra scanning and notifications when a file or directory is created or moved.

Requires the DDD system to kick-off extra scans.

Default: no

DisableCertCheck BOOL

Disable authenticode certificate chain verification in PE files.

Default: no

## NOTES
All options expressing a size are limited to max 4GB. Values in excess will be reset to the maximum.

## FILES
/etc/clamav/clamd.conf

## AUTHORS
Tomasz Kojm <tkojm@clamav.net>, Kevin Lin <klin@sourcefire.com>

## SEE ALSO
clamd(8), clamdscan(1), clamav-milter(8), freshclam(1), freshclam.conf(5)


freshclam.conf

title: freshclam.conf(5)

text:
# freshclam.conf(5)

## NAME
freshclam.conf - Configuration file for Clam AntiVirus database update tool

## DESCRIPTION
The file freshclam.conf configures the Clam AntiVirus Database Updater, freshclam(1).

## FILE FORMAT
The file consists of comments and options with arguments. Each line which starts with a hash (#) symbol is ignored by the parser. Options and arguments are case sensitive and of the form Option Argument. The arguments are of the following types:

BOOL

Boolean value (yes/no or true/false or 1/0).

STRING

String without blank characters.

SIZE

Size in bytes. You can use 'M' or 'm' modifiers for megabytes and 'K' or 'k' for kilobytes.

NUMBER

Unsigned integer.

## DIRECTIVES
When an option is not used (hashed or doesn't exist in the configuration file) freshclam takes a default action.

Example

If this option is set freshclam will not run.

LogFileMaxSize SIZE

Limit the size of the log file. The logger will be automatically disabled if the file is greater than SIZE. Value of 0 disables the limit.

Default: 1M

LogTime BOOL

Log time with each message.

Default: no

LogSyslog BOOL

Enable logging to Syslog. May be used in combination with UpdateLogFile.

Default: disabled.

LogFacility STRING

Specify the type of syslog messages - please refer to 'man syslog' for facility names.

Default: LOG_LOCAL6

LogVerbose BOOL

Enable verbose logging.

Default: disabled

LogRotate BOOL

Rotate log file. Requires LogFileMaxSize option set prior to this option.

Default: no

PidFile STRING

Write the daemon's pid to the specified file.

Default: disabled

DatabaseDirectory STRING

Path to a directory containing database files. This directory must already exist, be an absolute path, be writeable by freshclam and readable by clamd/clamscan.

Default: /var/lib/clamav

Foreground BOOL

Don't fork into background.

Default: no

Debug BOOL

Enable debug messages in libclamav.

Default: no

UpdateLogFile STRING

Enable logging to a specified file. Highly recommended.

Default: disabled.

DatabaseOwner STRING

When started by root, drop privileges to a specified user.

Default: mail

Checks NUMBER

Number of database checks per day.

Default: 12

DNSDatabaseInfo STRING

Use DNS to verify the virus database version. FreshClam uses DNS TXT records to verify the versions of the database and software itself. With this directive you can change the database verification domain.

WARNING: Please don't change it unless you're configuring freshclam to use your own database verification domain.

Default: enabled, pointing to current.cvd.clamav.net

DatabaseMirror STRING

DatabaseMirror specifies to which mirror(s) freshclam should connect. You should have at least one entries: database.clamav.net. Now that CloudFlare is being used as our Content Delivery Network (CDN), this one domain name works world-wide to direct freshclam to the closest geographic endpoint.

Default: database.clamav.net

PrivateMirror STR

This option allows you to easily point freshclam to private mirrors. If PrivateMirror is set, freshclam does not attempt to use DNS to determine whether its databases are out-of-date, instead it will use the If-Modified-Since request or directly check the headers of the remote database files. For each database, freshclam first attempts to download the CLD file. If that fails, it tries to download the CVD file. This option overrides DatabaseMirror, DNSDatabaseInfo and ScriptedUpdates. It can be used multiple times to provide fall-back mirrors.

Default: disabled

MaxAttempts NUMBER

How many attempts (per mirror) to make before giving up.

Default: 3 (per mirror)

ScriptedUpdates BOOL

With this option you can control scripted updates. It's highly recommended to keep it enabled.

Default: yes

TestDatabases BOOL

With this option enabled, freshclam will attempt to load new databases into memory to make sure they are properly handled by libclamav before replacing the old ones.

Default: enabled

CompressLocalDatabase BOOL

By default freshclam will keep the local databases (.cld) uncompressed to make their handling faster. With this option you can enable the compression; the change will take effect with the next database update.

Default: no

ExtraDatabase STRING

Download an additional 3rd party signature database distributed through the ClamAV mirrors. This option can be used multiple times.

Default: disabled

ExcludeDatabase STRING

Exclude a standard signature database (opt-out). This option can be used multiple times.

Default: disabled

DatabaseCustomURL STRING

With this option you can provide custom sources for database files. This option can be used multiple times. Support for:

http(s)://, ftp(s)://, or file:// Example usage:

DatabaseCustomURL https://myserver.com:4567/allow_list.wdb

Default: disabled

HTTPProxyServer STR, HTTPProxyPort NUMBER

Use given proxy server and TCP port for database downloads. The HTTPProxyServer may be prefixed with [scheme]:// to specify which kind of proxy is used.

http:// HTTP Proxy. Default when no scheme or proxy type is specified.

https:// HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)

socks4:// SOCKS4 Proxy.

socks4a:// SOCKS4a Proxy. Proxy resolves URL hostname.

socks5:// SOCKS5 Proxy.

socks5h:// SOCKS5 Proxy. Proxy resolves URL hostname.

HTTPProxyUsername STR,HTTPProxyPassword STRING

Proxy usage is authenticated through given username and password.

Default: disabled

HTTPUserAgent STRING

If your servers are behind a firewall/proxy which applies User-Agent filtering, you can use this option to force the use of a different User-Agent header. As of ClamAV 0.103.3, this setting may not be used when updating from the clamav.net CDN and can only be used when updating from a private mirror.

Default: clamav/version_number

NotifyClamd STRING

Notify a running clamd(8) to reload its database after a download has occurred. The path for clamd.conf file must be provided.

Default: The default is to not notify clamd. See clamd.conf(5)'s option SelfCheck for how clamd(8) handles database updates in this case.

OnUpdateExecute STRING

Execute this command after the database has been successfully updated.

Default: disabled

OnErrorExecute STRING

Execute this command after a database update has failed.

Default: disabled

OnOutdatedExecute STRING

Execute this command when freshclam reports outdated version. In the command string %v will be replaced by the new version number.

Default: disabled

LocalIPAddress IP

Use IP as client address for downloading databases. Useful for multi homed systems.

Default: Use OS'es default outgoing IP address.

ConnectTimeout NUMBER

Timeout in seconds when connecting to database server.

Default: 10

ReceiveTimeout NUMBER

Maximum time in seconds for each download operation. 0 means no timeout.

Default: 0

Bytecode BOOL

This option enables downloading of bytecode.cvd, which includes additional detection mechanisms and improvements to the ClamAV engine.

Default: yes

## FILES
/etc/clamav/freshclam.conf

## AUTHOR
Thomas Lamy <thomas.lamy@netwake.de>, Tomasz Kojm <tkojm@clamav.net>, Kevin Lin <klin@sourcefire.com>

## SEE ALSO
freshclam(1), clamd.conf(5), clamd(8), clamscan(1)


clamsmtpd.conf

package: clamsmtp

title: clamsmtpd.conf(5)

summary: the configuration file for

text:
# clamsmtpd.conf(5)

## NAME
clamsmtpd.conf — the configuration file for clamsmtpd(8)

## DESCRIPTION
clamsmtpd(8) reads a configuration file when starting up. The location of the file is dependent on how you compiled clamsmtp but it should usually be in either the /usr/local/etc/ or /etc/ directories. If clamsmtpd(8) does not find its configuration file it'll print a warning when it starts up along with the location it's expecting to find it in. You can also specify a different location for a config file by passing the -f argument to clamsmtpd(8)

The settings are specified one per line. The setting names come first, followed by a colon and then the value. Comments start with the '#' character on a line of their own. Whitespace is ignored at the beginning of line, end of line and around the colons.

A sample configuration file can be found in the doc/ directory of the clamsmtp distribution.

## SETTINGS
The various settings are as follows:

Action

This option controls what clamsmtpd(8) does when it finds a virus. The options are: bounce

Bounce the email. In most cases this is not a good idea since many viruses spoof sender addresses.

drop

Silently drop the email. Recommended.

pass

Pass on the email. Inserts an 'X-Virus-Infected' header.

[ Default: drop ]

ClamAddress

Specifies the address to connect to clamd(8) on. See syntax of addresses below. [ Default: /var/run/clamav/clamd ]

Header

A header to add to scanned messages. Put an empty value to suppress adding a header. You can include the following special formatting characters in the string to include special values: %i

Client IP Address

%l

Local IP Address

%d

Current Date

You can also include the standard \r or \n escapes.

[ Default: 'X-Virus-Scanned: ClamAV using ClamSMTP' ]

KeepAlives

On slow connections the server will sometimes timeout before clamsmtpd(8) is finished scanning the file. This option sends NOOP's to the server to keep the connection alive. Specify the number of seconds, or 0 to disable. [ Default: 0 ]

Listen

The address and port to listen for SMTP connections on. See syntax of addresses below. [ Default: port 10025 on all local IP addresses ]

PidFile

Specifies a location for the a process id file to be written to. This file contains the process id of clamsmtpd.conf and can be used to stop the daemon. If the -p argument is passed on the command line, then this setting will be ignored. [ Default: none ]

Quarantine

Quarantine files that contain viruses by leaving them in the TempDirectory directory. The file names look like this (where X is a random character or number): virus.XXXXXX [ Default: off ]

MaxConnections

Specifies the maximum number of connections to accept at once. clamd(8) also needs to be setup to accept at least this number of connections. [ Default: 64 ]

OutAddress

The address of the SMTP server to send email to once it's been scanned. See syntax of addreses below. [ Required ]

TempDirectory

The directory to write temp files to. This directory needs to be accessible to both clamd(8) and clamsmtpd(8) [ Default: /tmp ]

TimeOut

The number of seconds to wait while reading data from network connections. [ Default: 180 seconds ]

TransparentProxy

This option enables transparent proxy support, which allows you to route all SMTP traffic that's going through a gateway through clamsmtp which will then send it on to its final destination. This setup usually involves firewall rules which redirect traffic to clamsmtp, and the setup varies from OS to OS. [ Default: off ]

User

The user to run as. If this option is specified then clamsmtpd(8) must be started as root. It will then drop root privileges and run as the specified user. The user can either be a name or a numerical user id. [ Optional ]

VirusAction

This is a command to run when a virus is found. See the VIRUS ACTION section in clamsmtpd(8) for a discussion of this option. [ Default: off ]

XClient

Send an XCLIENT command to the receiving server. This is useful for forwarding client addresses and connection info to servers that support this feature. [ Default: off ]

## ADDRESSES
Addresses can be specified in multiple formats:

- Unix local addresses can be specified by specifying their full path. (ie: '/var/run/clamav/clamd').

- IP addresses can be specified using dotted notation with a colon before the port number (ie: '127.0.0.1:3310').

- IPv6 addresses are implemented but disabled. The code needs testing.

## SEE ALSO
clamsmtpd(8)

## AUTHOR
Stef Walter ⟨stef@memberwebs.com⟩


cockpit.conf

package: cockpit-ws

title: cockpit.conf(5)

summary: Cockpit configuration file

text:
# cockpit.conf(5)

## NAME
cockpit.conf - Cockpit configuration file

## DESCRIPTION
Cockpit can be configured via /etc/cockpit/cockpit.conf. This file is not required and may need to be created manually. The file has a INI file syntax and thus contains key / value pairs, grouped into topical groups. See the examples below for details..

Note: The port that cockpit listens on cannot be changed in this file. To change the port change the systemd cockpit.socket file.

## WEBSERVICE
Origins

By default cockpit will not accept crossdomain websocket connections. Use this setting to allow access from alternate domains. Origins should include scheme, host and port, if necessary.

```
[WebService]
Origins = https://somedomain1.com https://somedomain2.com:9090
```

ProtocolHeader

Configure cockpit to look at the contents of this header to determine if a connection is using tls. This should only be used when cockpit is behind a reverse proxy, and care should be taken to make sure that incoming requests cannot set this header.

```
[WebService]
ProtocolHeader = X-Forwarded-Proto
```

LoginTitle

Set the browser title for the login screen.

LoginTo

When set to true the Connect to option on the login screen is visible and allows logging into another server. If this option is not specified then it will be automatically detected based on whether the cockpit-ssh process is available or not.

RequireHost

When set to true cockpit will require users to use the Connect to option to specify the host to log into.

MaxStartups

Same as the sshd configuration option by the same name. Specifies the maximum number of concurrent login attempts allowed. Additional connections will be dropped until authentication succeeds or the connections are closed. Defaults to 10. Alternatively, random early drop can be enabled by specifying the three colon separated values start:rate:full (e.g. "10:30:60"). Cockpit will start refusing authentication attempts with a probability of rate/100 (30%) if there are currently start (10) unauthenticated connections. The probability increases linearly and all connection attempts are refused if the number of unauthenticated connections reaches full (60).

AllowUnencrypted

If true, cockpit will accept unencrypted HTTP connections. Otherwise, it redirects all HTTP connections to HTTPS. Exceptions are connections from localhost and for certain URLs (like /ping). Defaults to false.

UrlRoot

The root URL where you will be serving cockpit. When provided cockpit will expect all requests to be prefixed with the given url. This is mostly useful when you are using cockpit behind a reverse proxy, such as nginx. /cockpit/ and /cockpit+ are reserved and should not be used. For example /cockpit-new/ is ok. /cockpit/ and /cockpit+new/ are not.

ClientCertAuthentication

If true, enable TLS client certificates for authenticating users. Commonly these are provided by a smart card, but it's equally possible to import certificates directly into the web browser. Please see the Certificate/smart card authentication[1] section in the Cockpit guide for details.

Shell

The relative URL to top level component to display in Cockpit once logged in. Defaults to /shell/index.html

## LOG
Fatal

The kind of log messages in the bridge to treat as fatal. Separate multiple values with spaces. Relevant values are: criticals and warnings.

## OAUTH
Cockpit can be configured to support the implicit grant[2] OAuth authorization flow. When successful the resulting oauth token will be passed to cockpit-ws using the Bearer auth-scheme. For a login to be successful, cockpit will also need a to be configured to verify and allow Bearer tokens.

URL

This is the url that cockpit will redirect the users browser to when it needs to obtain an oauth token. Cockpit will add a redirect_uri parameter to the url with the location of where the oauth provider should redirect to once a token has been obtained.

ErrorParam

When a oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find a error message. When not provided it will default to error_description

TokenParam

When a oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find the access token. When not provided it will default to access_token

## SESSION
Banner

The contents of the specified file (commonly /etc/issue) are shown on the login page. By default, no banner is displayed.

IdleTimeout

Time in minutes after which session expires and user is logged out if no user action has been performed in the given time. This idle timeout only applies to interactive password logins. With non-interactive authentication methods like Kerberos, OAuth, or certificate login, the browser cannot forget credentials, and thus automatic logouts are not useful for protecting credentials of forgotten sessions. Set to 0 to disable session timeout.

```
[Session]
IdleTimeout=15
```

When not specified, there is no idle timeout by default.

## BUGS
Please send bug reports to either the distribution bug tracker or the upstream bug tracker[3].

## AUTHOR
Cockpit has been written by many contributors[4].

## SEE ALSO
cockpit-ws(8), cockpit-tls(8)

## NOTES
1.

Certificate/smart card authentication

https://cockpit-project.org/guide/latest/cert-authentication.html

2.

implicit grant

https://tools.ietf.org/html/rfc6749#section-4.2

3.

upstream bug tracker

https://github.com/cockpit-project/cockpit/issues/new

4.

contributors

https://github.com/cockpit-project/cockpit/


collectd-email

package: collectd

title: collectd-email(5)

summary: Documentation of collectd's email plugin

text:
# collectd-email(5)

## NAME
collectd-email - Documentation of collectd's "email plugin"

## SYNOPSIS

```
  # See collectd.conf(5)
  LoadPlugin email
  # ...
  <Plugin email>
    SocketGroup "collectd"
    SocketPerms "0770"
    MaxConns 5
  </Plugin>
```

## DESCRIPTION
The "email plugin" opens an UNIX-socket over which one can submit email statistics, such as the number of "ham", "spam", "virus", etc. mails received/handled, spam scores and matched spam checks.

This plugin is intended to be used with the Mail::SpamAssassin::Plugin::Collectd SpamAssassin-plugin which is included in contrib/, but is of course not limited to that use.

## OPERATION
This plugin collects data indirectly by providing a UNIX-socket that external programs can connect to. A simple line based protocol is used to communicate with the plugin:

- E-Mail type (e.g. "ham", "spam", "virus", ...) and size (bytes):

```
  e:<type>:<size>

```

If "size" is less than or equal to zero, "size" is ignored.

- Spam score:

```
  s:<value>

```

- Successful spam checks (e.g. "BAYES_99", "SUBJECT_DRUG_GAP_C", ...):

```
  c:<type1>[,<type2>,...]

```

Each line is limited to 256 characters (including the newline character). Longer lines will be ignored.

## SEE ALSO
collectd(1), collectd.conf(5)

## AUTHOR
The "email plugin" has been written by Sebastian Harl <sh at tokkee.org>.

The SpamAssassin-plugin has been written by Alexander Wirt <formorer at formorer.de>.

This manpage has been written by Florian Forster <octo at collectd.org>.


collectd-exec

title: collectd-exec(5)

summary: Documentation of collectd's exec plugin

text:
# collectd-exec(5)

## NAME
collectd-exec - Documentation of collectd's "exec plugin"

## SYNOPSIS

```
  # See collectd.conf(5)
  LoadPlugin exec
  # ...
  <Plugin exec>
    Exec "myuser:mygroup" "myprog"
    Exec "otheruser" "/path/to/another/binary" "arg0" "arg1"
    NotificationExec "user" "/usr/lib/collectd/exec/handle_notification"
  </Plugin>
```

## DESCRIPTION
The "exec plugin" forks off an executable either to receive values or to dispatch notifications to the outside world. The syntax of the configuration is explained in collectd.conf(5) but summarized in the above synopsis.

If you want/need better performance or more functionality you should take a long look at the "perl plugin", collectd-perl(5).

## EXECUTABLE TYPES
There are currently two types of executables that can be executed by the "exec plugin":

"Exec"

These programs are forked and values that it writes to "STDOUT" are read back. The executable is forked in a fashion similar to init: It is forked once and not again until it exits. If it exited, it will be forked again after at most Interval seconds. It is perfectly legal for the executable to run for a long time and continuously write values to "STDOUT". See "EXEC DATA FORMAT" below for a description of the output format expected from these programs.

Warning: If the executable only writes one value and then exits it will be executed every Interval seconds. If Interval is short (the default is 10 seconds) this may result in serious system load.

"NotificationExec"

The program is forked once for each notification that is handled by the daemon. The notification is passed to the program on "STDIN" in a fashion similar to HTTP-headers. In contrast to programs specified with "Exec" the execution of this program is not serialized, so that several instances of this program may run at once if multiple notifications are received. See "NOTIFICATION DATA FORMAT" below for a description of the data passed to these programs.

## EXEC DATA FORMAT
The forked executable is expected to print values to "STDOUT". The expected format is as follows:

Comments

Each line beginning with a "#" (hash mark) is ignored.

PUTVAL Identifier [OptionList] Valuelist

Submits one or more values (identified by Identifier, see below) to the daemon which will dispatch it to all its write-plugins. An Identifier is of the form "host/plugin-instance/type-instance" with both instance-parts being optional. If they're omitted the hyphen must be omitted, too. plugin and each instance-part may be chosen freely as long as the tuple (plugin, plugin instance, type instance) uniquely identifies the plugin within collectd. type identifies the type and number of values (i. e. data-set) passed to collectd. A large list of predefined data-sets is available in the types.db file. See types.db(5) for a description of the format of this file.

The OptionList is an optional list of Options, where each option is a key-value-pair. A list of currently understood options can be found below, all other options will be ignored. Values that contain spaces must be quoted with double quotes.

Valuelist is a colon-separated list of the time and the values, each either an integer if the data-source is a counter, or a double if the data-source is of type "gauge". You can submit an undefined gauge-value by using U. When submitting U to a counter the behavior is undefined. The time is given as epoch (i. e. standard UNIX time) or N to use the current time.

You can mix options and values, but the order is important: Options only effect following values, so specifying an option as last field is allowed, but useless. Also, an option applies to all following values, so you don't need to re-set an option over and over again.

The currently defined Options are:

interval=seconds

Gives the interval in which the data identified by Identifier is being collected.

meta:key=value

Add meta data with the key key and the value value.

Please note that this is the same format as used in the unixsock plugin, see collectd-unixsock(5). There's also a bit more information on identifiers in case you're confused.

Since examples usually let one understand a lot better, here are some:

```
  PUTVAL leeloo/cpu-0/cpu-idle N:2299366
  PUTVAL alice/interface/if_octets-eth0 interval=10 1180647081:421465:479194
```

PUTNOTIF [OptionList] message=Message

Submits a notification to the daemon which will then dispatch it to all plugins which have registered for receiving notifications. The PUTNOTIF if followed by a list of options which further describe the notification. The message option is special in that it will consume the rest of the line as its value. The message, severity, and time options are mandatory.

Valid options are:

message=Message (REQUIRED)

Sets the message of the notification. This is the message that will be made accessible to the user, so it should contain some useful information. As with all options: If the message includes spaces, it must be quoted with double quotes. This option is mandatory.

severity=failure|warning|okay (REQUIRED)

Sets the severity of the notification. This option is mandatory.

time=Time (REQUIRED)

Sets the time of the notification. The time is given as "epoch", i. e. as seconds since January 1st, 1970, 00:00:00. This option is mandatory.

host=Hostname

plugin=Plugin

plugin_instance=Plugin-Instance

type=Type

type_instance=Type-Instance

These "associative" options establish a relation between this notification and collected performance data. This connection is purely informal, i. e. the daemon itself doesn't do anything with this information. However, websites or GUIs may use this information to place notifications near the affected graph or table. All the options are optional, but plugin_instance without plugin or type_instance without type doesn't make much sense and should be avoided.

type:key=value

Sets user defined meta information. The type key is a single character defining the type of the meta information. The current supported types are:

s A string passed as-is.

Please note that this is the same format as used in the unixsock plugin, see collectd-unixsock(5).

When collectd exits it sends a SIGTERM to all still running child-processes upon which they have to quit.

## NOTIFICATION DATA FORMAT
The notification executables receive values rather than providing them. In fact, after the program is started "STDOUT" is connected to "/dev/null".

The data is passed to the executables over "STDIN" in a format very similar to HTTP: At first there is a "header" with one line per field. Every line consists of a field name, ended by a colon, and the associated value until end-of-line. The "header" is ended by two newlines immediately following another, i.e. an empty line. The rest, basically the "body", is the message of the notification.

The following is an example notification passed to a program:

```
  Severity: FAILURE
  Time: 1200928930.515
  Host: myhost.mydomain.org
  \n
  This is a test notification to demonstrate the format
```

The following header files are currently used. Please note, however, that you should ignore unknown header files to be as forward-compatible as possible.

Severity

Severity of the notification. May either be FAILURE, WARNING, or OKAY.

Time

The time in epoch, i.e. as seconds since 1970-01-01 00:00:00 UTC. The value currently has millisecond precision (i.e. three decimal places), but scripts should accept arbitrary numbers of decimal places, including no decimal places.

Host

Plugin

PluginInstance

Type

TypeInstance

Identification of the performance data this notification is associated with. All of these fields are optional because notifications do not need to be associated with a certain value.

## ENVIRONMENT
The following environment variables are set by the plugin before calling exec:

COLLECTD_INTERVAL

Value of the global interval setting.

COLLECTD_HOSTNAME

Hostname used by collectd to dispatch local values.

## USING NAGIOS PLUGINS
Though the interface is far from perfect, there are tons of plugins for Nagios. You can use these plugins with collectd by using a simple transition layer, "exec-nagios.px", which is shipped with the collectd distribution in the "contrib/" directory. It is a simple Perl script that comes with embedded documentation. To see it, run the following command:

```
  perldoc exec-nagios.px
```

This script expects a configuration file, "exec-nagios.conf". You can find an example in the "contrib/" directory, too.

Even a simple mechanism to submit "performance data" to collectd is implemented. If you need a more sophisticated setup, please rewrite the plugin to make use of collectd's more powerful interface.

## CAVEATS

- The user, the binary is executed as, may not have root privileges, i. e. must have an UID that is non-zero. This is for your own good.

- Early versions of the plugin did not use a command but treated all lines as if they were arguments to the PUTVAL command. When the PUTNOTIF command was implemented, this behavior was kept for lines which start with an unknown command for backwards compatibility. This compatibility code has been removed in collectd 5.

## SEE ALSO
collectd(1), collectd.conf(5), collectd-perl(5), collectd-unixsock(5), fork(2), exec(3)

## AUTHOR
Florian Forster <octo@collectd.org>


collectd-java

title: collectd-java(5)

summary: Documentation of collectd's java plugin

text:
# collectd-java(5)

## NAME
collectd-java - Documentation of collectd's "java plugin"

## SYNOPSIS

```
 LoadPlugin "java"
 <Plugin "java">
   JVMArg "-verbose:jni"
   JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"

   LoadPlugin "org.collectd.java.Foobar"
   <Plugin "org.collectd.java.Foobar">
     # To be parsed by the plugin
   </Plugin>
 </Plugin>
```

## DESCRIPTION
The Java plugin embeds a Java Virtual Machine (JVM) into collectd and provides a Java interface to part of collectd's API. This makes it possible to write additions to the daemon in Java.

This plugin is similar in nature to, but shares no code with, the Perl plugin by Sebastian Harl, see collectd-perl(5) for details.

## CONFIGURATION
A short outline of this plugin's configuration can be seen in "SYNOPSIS" above. For a complete list of all configuration options and their semantics please read "Plugin "java"" in collectd.conf(5).

## OVERVIEW
When writing additions for collectd in Java, the underlying C base is mostly hidden from you. All complex data types are converted to their Java counterparts before they're passed to your functions. These Java classes reside in the org.collectd.api namespace.

The Java plugin will create one object of each class configured with the LoadPlugin option. The constructor of this class can then register "callback methods", i. e. methods that will be called by the daemon when appropriate.

The available classes are:

org.collectd.api.Collectd

All API functions exported to Java are implemented as static functions of this class. See "EXPORTED API FUNCTIONS" below.

org.collectd.api.OConfigValue

Corresponds to "oconfig_value_t", defined in src/liboconfig/oconfig.h.

org.collectd.api.OConfigItem

Corresponds to "oconfig_item_t", defined in src/liboconfig/oconfig.h.

org.collectd.api.DataSource

Corresponds to "data_source_t", defined in src/plugin.h.

org.collectd.api.DataSet

Corresponds to "data_set_t", defined in src/plugin.h.

org.collectd.api.ValueList

Corresponds to "value_list_t", defined in src/plugin.h.

org.collectd.api.Notification

Corresponds to "notification_t", defined in src/plugin.h.

In the remainder of this document, we'll use the short form of these names, for example ValueList. In order to be able to use these abbreviated names, you need to import the classes.

## EXPORTED API FUNCTIONS
All collectd API functions that are available to Java plugins are implemented as public static functions of the Collectd class. This makes calling these functions pretty straight forward. For example, to send an error message to the daemon, you'd do something like this:

```
  Collectd.logError ("That wasn't chicken!");
```

The following are the currently exported functions.

### registerConfig
Signature: int registerConfig (String name, CollectdConfigInterface object);

Registers the config function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "config callback" below.

### registerInit
Signature: int registerInit (String name, CollectdInitInterface object);

Registers the init function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "init callback" below.

### registerRead
Signature: int registerRead (String name, CollectdReadInterface object)

Registers the read function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "read callback" below.

### registerWrite
Signature: int registerWrite (String name, CollectdWriteInterface object)

Registers the write function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "write callback" below.

### registerFlush
Signature: int registerFlush (String name, CollectdFlushInterface object)

Registers the flush function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "flush callback" below.

### registerShutdown
Signature: int registerShutdown (String name, CollectdShutdownInterface object);

Registers the shutdown function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "shutdown callback" below.

### registerLog
Signature: int registerLog (String name, CollectdLogInterface object);

Registers the log function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "log callback" below.

### registerNotification
Signature: int registerNotification (String name, CollectdNotificationInterface object);

Registers the notification function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "notification callback" below.

### registerMatch
Signature: int registerMatch (String name, CollectdMatchFactoryInterface object);

Registers the createMatch function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "match callback" below.

### registerTarget
Signature: int registerTarget (String name, CollectdTargetFactoryInterface object);

Registers the createTarget function of object with the daemon.

Returns zero upon success and non-zero when an error occurred.

See "target callback" below.

### dispatchValues
Signature: int dispatchValues (ValueList)

Passes the values represented by the ValueList object to the "plugin_dispatch_values" function of the daemon. The "data set" (or list of "data sources") associated with the object are ignored, because "plugin_dispatch_values" will automatically lookup the required data set. It is therefore absolutely okay to leave this blank.

Returns zero upon success or non-zero upon failure.

### getDS
Signature: DataSet getDS (String)

Returns the appropriate type or null if the type is not defined.

### logError
Signature: void logError (String)

Sends a log message with severity ERROR to the daemon.

### logWarning
Signature: void logWarning (String)

Sends a log message with severity WARNING to the daemon.

### logNotice
Signature: void logNotice (String)

Sends a log message with severity NOTICE to the daemon.

### logInfo
Signature: void logInfo (String)

Sends a log message with severity INFO to the daemon.

### logDebug
Signature: void logDebug (String)

Sends a log message with severity DEBUG to the daemon.

## REGISTERING CALLBACKS
When starting up, collectd creates an object of each configured class. The constructor of this class should then register "callbacks" with the daemon, using the appropriate static functions in Collectd, see "EXPORTED API FUNCTIONS" above. To register a callback, the object being passed to one of the register functions must implement an appropriate interface, which are all in the org.collectd.api namespace.

A constructor may register any number of these callbacks, even none. An object without callback methods is never actively called by collectd, but may still call the exported API functions. One could, for example, start a new thread in the constructor and dispatch (submit to the daemon) values asynchronously, whenever one is available.

Each callback method is now explained in more detail:

### config callback
Interface: org.collectd.api.CollectdConfigInterface

Signature: int config (OConfigItem ci)

This method is passed a OConfigItem object, if both, method and configuration, are available. OConfigItem is the root of a tree representing the configuration for this plugin. The root itself is the representation of the <Plugin /> block, so in next to all cases the children of the root are the first interesting objects.

To signal success, this method has to return zero. Anything else will be considered an error condition and the plugin will be disabled entirely.

See "registerConfig" above.

### init callback
Interface: org.collectd.api.CollectdInitInterface

Signature: int init ()

This method is called after the configuration has been handled. It is supposed to set up the plugin. e. g. start threads, open connections, or check if can do anything useful at all.

To signal success, this method has to return zero. Anything else will be considered an error condition and the plugin will be disabled entirely.

See "registerInit" above.

### read callback
Interface: org.collectd.api.CollectdReadInterface

Signature: int read ()

This method is called periodically and is supposed to gather statistics in whatever fashion. These statistics are represented as a ValueList object and sent to the daemon using dispatchValues.

To signal success, this method has to return zero. Anything else will be considered an error condition and cause an appropriate message to be logged. Currently, returning non-zero does not have any other effects. In particular, Java "read"-methods are not suspended for increasing intervals like C "read"-functions.

See "registerRead" above.

### write callback
Interface: org.collectd.api.CollectdWriteInterface

Signature: int write (ValueList vl)

This method is called whenever a value is dispatched to the daemon. The corresponding C "write"-functions are passed a "data_set_t", so they can decide which values are absolute values (gauge) and which are counter values. To get the corresponding "List<DataSource>", call the getDataSource method of the ValueList object.

To signal success, this method has to return zero. Anything else will be considered an error condition and cause an appropriate message to be logged.

See "registerWrite" above.

### flush callback
Interface: org.collectd.api.CollectdFlushInterface

Signature: int flush (int timeout, String identifier)

This method is called when the daemon received a flush command. This can either be done using the "USR1" signal (see collectd(1)) or using the unixsock plugin (see collectd-unixsock(5)).

If timeout is greater than zero, only values older than this number of seconds should be flushed. To signal that all values should be flushed regardless of age, this argument is set to a negative number.

The identifier specifies which value should be flushed. If it is not possible to flush one specific value, flush all values. To signal that all values should be flushed, this argument is set to null.

To signal success, this method has to return zero. Anything else will be considered an error condition and cause an appropriate message to be logged.

See "registerFlush" above.

### shutdown callback
Interface: org.collectd.api.CollectdShutdownInterface

Signature: int shutdown ()

This method is called when the daemon is shutting down. You should not rely on the destructor to clean up behind the object but use this function instead.

To signal success, this method has to return zero. Anything else will be considered an error condition and cause an appropriate message to be logged.

See "registerShutdown" above.

### log callback
Interface: org.collectd.api.CollectdLogInterface

Signature: void log (int severity, String message)

This callback can be used to receive log messages from the daemon.

The argument severity is one of:

- org.collectd.api.Collectd.LOG_ERR

- org.collectd.api.Collectd.LOG_WARNING

- org.collectd.api.Collectd.LOG_NOTICE

- org.collectd.api.Collectd.LOG_INFO

- org.collectd.api.Collectd.LOG_DEBUG

The function does not return any value.

See "registerLog" above.

### notification callback
Interface: org.collectd.api.CollectdNotificationInterface

Signature: int notification (Notification n)

This callback can be used to receive notifications from the daemon.

To signal success, this method has to return zero. Anything else will be considered an error condition and cause an appropriate message to be logged.

See "registerNotification" above.

### match callback
The match (and target, see "target callback" below) callbacks work a bit different from the other callbacks above: You don't register a match callback with the daemon directly, but you register a function which, when called, creates an appropriate object. The object creating the "match" objects is called "match factory".

See "registerMatch" above.

Factory object

Interface: org.collectd.api.CollectdMatchFactoryInterface

Signature: CollectdMatchInterface createMatch (OConfigItem ci);

Called by the daemon to create "match" objects.

Returns: A new object which implements the CollectdMatchInterface interface.

Match object

Interface: org.collectd.api.CollectdMatchInterface

Signature: int match (DataSet ds, ValueList vl);

Called when processing a chain to determine whether or not a ValueList matches. How values are matches is up to the implementing class.

Has to return one of:

- Collectd.FC_MATCH_NO_MATCH

- Collectd.FC_MATCH_MATCHES

### target callback
The target (and match, see "match callback" above) callbacks work a bit different from the other callbacks above: You don't register a target callback with the daemon directly, but you register a function which, when called, creates an appropriate object. The object creating the "target" objects is called "target factory".

See "registerTarget" above.

Factory object

Interface: org.collectd.api.CollectdTargetFactoryInterface

Signature: CollectdTargetInterface createTarget (OConfigItem ci);

Called by the daemon to create "target" objects.

Returns: A new object which implements the CollectdTargetInterface interface.

Target object

Interface: org.collectd.api.CollectdTargetInterface

Signature: int invoke (DataSet ds, ValueList vl);

Called when processing a chain to perform some action. The action performed is up to the implementing class.

Has to return one of:

- Collectd.FC_TARGET_CONTINUE

- Collectd.FC_TARGET_STOP

- Collectd.FC_TARGET_RETURN

## EXAMPLE
This short example demonstrates how to register a read callback with the daemon:

```
  import org.collectd.api.Collectd;
  import org.collectd.api.ValueList;

  import org.collectd.api.CollectdReadInterface;

  public class Foobar implements CollectdReadInterface
  {
    public Foobar ()
    {
      Collectd.registerRead ("Foobar", this);
    }

    public int read ()
    {
      ValueList vl;

      /* Do something... */

      Collectd.dispatchValues (vl);
    }
  }
```

## PLUGINS
The following plugins are implemented in Java. Both, the LoadPlugin option and the Plugin block must be inside the <Plugin java> block (see above).

### GenericJMX plugin
The GenericJMX plugin reads Managed Beans (MBeans) from an MBeanServer using JMX. JMX is a generic framework to provide and query various management information. The interface is used by Java processes to provide internal statistics as well as by the Java Virtual Machine (JVM) to provide information about the memory used, threads and so on.

The configuration of the GenericJMX plugin consists of two blocks: MBean blocks that define a mapping of MBean attributes to the XtypesX used by collectd, and Connection blocks which define the parameters needed to connect to an MBeanServer and what data to collect. The configuration of the SNMP plugin is similar in nature, in case you know it.

MBean blocks

MBean blocks specify what data is retrieved from MBeans and how that data is mapped on the collectd data types. The block requires one string argument, a name. This name is used in the Connection blocks (see below) to refer to a specific MBean block. Therefore, the names must be unique.

The following options are recognized within MBean blocks:

ObjectName pattern

Sets the pattern which is used to retrieve MBeans from the MBeanServer. If more than one MBean is returned you should use the InstanceFrom option (see below) to make the identifiers unique. See also: <http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>

InstancePrefix prefix

Prefixes the generated plugin instance with prefix. (optional)

InstanceFrom property

The object names used by JMX to identify MBeans include so called XpropertiesX which are basically key-value-pairs. If the given object name is not unique and multiple MBeans are returned, the values of those properties usually differ. You can use this option to build the plugin instance from the appropriate property values. This option is optional and may be repeated to generate the plugin instance from multiple property values.

<value /> blocks

The value blocks map one or more attributes of an MBean to a value list in collectd. There must be at least one Value block within each MBean block.

Type type

Sets the data set used within collectd to handle the values of the MBean attribute.

InstancePrefix prefix

Works like the option of the same name directly beneath the MBean block, but sets the type instance instead. (optional)

InstanceFrom prefix

Works like the option of the same name directly beneath the MBean block, but sets the type instance instead. (optional)

PluginName name

When set, overrides the default setting for the plugin field ("GenericJMX").

Table true|false

Set this to true if the returned attribute is a composite type. If set to true, the keys within the composite type is appended to the type instance.

Attribute path

Sets the name of the attribute from which to read the value. You can access the keys of composite types by using a dot to concatenate the key name to the attribute name. For example: Xattrib0.key42X. If Table is set to true path must point to a composite type, otherwise it must point to a numeric type.

Connection blocks

Connection blocks specify how to connect to an MBeanServer and what data to retrieve. The following configuration options are available:

Host name

Host name used when dispatching the values to collectd. The option sets this field only, it is not used to connect to anything and doesn't need to be a real, resolvable name.

ServiceURL URL

Specifies how the MBeanServer can be reached. Any string accepted by the JMXServiceURL is valid. See also: <http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>

User name

Use name to authenticate to the server. If not configured, XmonitorRoleX will be used.

Password password

Use password to authenticate to the server. If not given, unauthenticated access is used.

InstancePrefix prefix

Prefixes the generated plugin instance with prefix. If a second InstancePrefix is specified in a referenced MBean block, the prefix specified in the Connection block will appear at the beginning of the plugin instance, the prefix specified in the MBean block will be appended to it.

Collect mbean_block_name

Configures which of the MBean blocks to use with this connection. May be repeated to collect multiple MBeans from this server.

## SEE ALSO
collectd(1), collectd.conf(5), collectd-perl(5), types.db(5)

## AUTHOR
Florian Forster <octo at collectd.org>


collectd-lua

title: collectd-lua(5)

summary: Documentation of collectd's Lua plugin

text:
# collectd-lua(5)

## NAME
collectd-lua - Documentation of collectd's "Lua plugin"

## SYNOPSIS

```
  LoadPlugin lua
  # ...
  <Plugin lua>
    BasePath "/path/to/your/lua/scripts"
    Script "script1.lua"
    Script "script2.lua"
  </Plugin>
```

## DESCRIPTION
The "Lua plugin" embeds a Lua interpreter into collectd and provides an interface to collectd's plugin system. This makes it possible to write plugins for collectd in Lua. This is a lot more efficient than executing a Lua script every time you want to read a value with the "exec plugin" (see collectd-exec(5)) and provides a lot more functionality, too.

The minimum required Lua version is 5.1.

## CONFIGURATION
LoadPlugin Lua

Loads the Lua plugin.

BasePath Name

The directory the "Lua plugin" looks in to find script Script. If set, this is also prepended to package.path.

Script Name

The script the "Lua plugin" is going to run. If BasePath is not specified, this needs to be an absolute path.

## WRITING YOUR OWN PLUGINS
Writing your own plugins is quite simple. collectd manages plugins by means of dispatch functions which call the appropriate callback functions registered by the plugins. Any plugin basically consists of the implementation of these callback functions and initializing code which registers the functions with collectd. See the section "EXAMPLES" below for a really basic example. The following types of callback functions are implemented in the Lua plugin (all of them are optional):

read functions

These are used to collect the actual data. It is called once per interval (see the Interval configuration option of collectd). Usually it will call collectd.dispatch_values to dispatch the values to collectd which will pass them on to all registered write functions. If this function does not return 0, interval between its calls will grow until function returns 0 again. See the MaxReadInterval configuration option of collectd.

write functions

These are used to write the dispatched values. They are called once for every value that was dispatched by any plugin.

## FUNCTIONS
The following functions are provided to Lua modules:

register_read(callback)

Function to register read callbacks. The callback will be called without arguments. If this callback function does not return 0 the next call will be delayed by an increasing interval.

register_write(callback)

Function to register write callbacks. The callback function will be called with one argument passed, which will be a table of values. If this callback function does not return 0 next call will be delayed by an increasing interval.

log_error, log_warning, log_notice, log_info, log_debug(message)

Log a message with the specified severity.

## EXAMPLES
A very simple read function might look like:

```
  function read()
    collectd.log_info("read function called")
    t = {
        host = 'localhost',
        plugin = 'myplugin',
        type = 'counter',
        values = {42},
    }
    collectd.dispatch_values(t)
    return 0
  end
```

A very simple write function might look like:

```
  function write(vl)
    for i = 1, #vl.values do
      collectd.log_info(vl.host .. '.' .. vl.plugin .. '.' .. vl.type .. ' ' .. vl.values[i])
    end
    return 0
  end
```

To register those functions with collectd:

```
  collectd.register_read(read)     -- pass function as variable
  collectd.register_write("write") -- pass by global-scope function name
```

## SEE ALSO
collectd(1), collectd.conf(5), lua(1),

## AUTHOR
The "Lua plugin" has been written by Julien Ammous <j.ammous at gmail.com>, Florian Forster <octo at collectd.org> and Ruben Kerkhof <ruben at rubenkerkhof.com>.

This manpage has been written by Ruben Kerkhof <ruben at rubenkerkhof.com>. It is based on the collectd-perl(5) manual page by Florian Forster <octo at collectd.org> and Sebastian Harl <sh at tokkee.org>.