dccm

title: dccm(8)

text:
# dccm(8)

## NAME
dccm — Distributed Checksum Clearinghouse Milter Interface

## SYNOPSIS
dccm

[-VdbxANPQ] [-G on | off | noIP | IPmask/xx] [-h homedir] [-I user]

[-p protocol:filename | protocol:port@host] [-m map]

[-w whiteclnt] [-U userdirs] [-a IGNORE | REJECT | DISCARD]

[-t type,[log-thold,]rej-thold] [-g [not-]type] [-S header]

[-l logdir] [-R rundir] [-r rejection-msg] [-j maxjobs] [-B dnsbl-option] [-L ltype,facility.level]

## DESCRIPTION
dccm is a daemon built with the sendmail milter interface intended to connect sendmail(8) to DCC servers. When built with the milter filter machinery and configured to talk to dccm in the sendmail.cf file, sendmail passes all email to dccm which in turn reports related checksums to the nearest DCC server. dccm then adds an X-DCC SMTP header line to the message. Sendmail is told to reject the message if it is unsolicited bulk mail.

Dccm sends reports of checksums related to mail received by DCC clients and queries about the total number of reports of particular checksums. A DCC server receives no mail, address, headers, or other information, but only cryptographically secure checksums of such information. A DCC server cannot determine the text or other information that corresponds to the checksums it receives. Its only acts as a clearinghouse of counts for checksums computed by clients. For complete privacy as far as the DCC is concerned, the checksums of purely internal mail or other mail that is known to not be unsolicited bulk can be listed in a whitelist to not be reported to the DCC server.

Since the checksums of messages that are whitelisted locally by the /var/lib/dcc/whiteclnt file are not reported to the DCC server, dccm knows nothing about the total recipient counts for their checksums and so cannot add X-DCC header lines to such messages. Sendmail does not tell dccm about messages that are not received by sendmail via SMTP, including messages submitted locally and received via UUCP, and so they also do not receive X-DCC header lines.

Enable the daemon and put its parameters in the /var/lib/dcc/conf file and start the daemon with the /usr/lib/dcc/start-dccm or /usr/lib/dcc/rcDCC scripts.

The list of servers that dccm contacts is in the memory mapped file /var/lib/dcc/map shared by local DCC clients. The file is maintained with cdcc(8).

### OPTIONS
The following options are available:

-V

displays the version of dccm. Two or more -V options show the options with which it was built.

-d

enables debugging output from the DCC client software. Additional -d options increase the number of messages. A single -d logs aborted SMTP transactions including those from some "dictionary attacks."

-b

causes the daemon to not detach itself from the controlling tty and put itself into the background.

-x

causes the daemon to try "extra hard" to contact a DCC server. Since it is usually more important to deliver mail than to report its checksums, dccm normally does not delay too long while trying to contact a DCC server. It will not try again for several seconds after a failure. With -x, it will always try to contact the DCC server and it will tell the MTA to answer the DATA command with a 4yz temporary failure.

-A

adds to existing X-DCC headers in the message instead of replacing existing headers of the brand of the current server.

-N

neither adds, deletes, nor replaces existing X-DCC headers in the message. Each mail message is logged, rejected, and otherwise handled the same.

-P

The SpamAsassin DCC.pm plugin should watch for "bulk" in X-DCC SMTP header fields, but historically has looked for counts of "many". However, there are situations when dccm knows that a mail message is extremely bulky and probably spam. For example, mail from a sender that is blacklisted in whiteclnt gets an X-DCC header that includes bulk. To acommodate that bug in SpamAssassin, by default whenever dccm generates an X-DCC header containing "bulk", it also forces the Body count to "many". -P turns off that kludge and the Body contains the count from the DCC server.

-Q

only queries the DCC server about the checksums of messages instead of reporting. This is useful when dccm is used to filter mail that has already been reported to a DCC server by another DCC client. No single mail message should be reported to a DCC server more than once per recipient, because each report will increase the apparent "bulkness" of the message. It is better to use MXDCC lines in the global /var/lib/dcc/whiteclnt file for your MX mail servers that use DCC than to use -Q with dccm.

Do not use -Q except on mail that you know has been reported to a DCC server. DCC depends on reports of all except known private mail and works only because almost no DCC installations use -Q.

-G on | off | noIP | IPmask/xx

controls greylisting. At least one working greylist server must be listed in the /var/lib/dcc/map file. If more than one is named, they must "flood" or change checksums and they must use the same -G parameters. See dccd(8). Usually all dccm or dccifd DCC client processes use the same -G parameters. IPmask/xx and noIP remove part or all of the IP address from the greylist triple.

-h homedir

overrides the default DCC home directory, /var/lib/dcc.

-I user

specifies the UID and GID of the process.

-p protocol:filename | protocol:port@host

specifies the protocol and address by which sendmail will contact dccm. The default is a UNIX domain socket in the "run" directory, /var/run/dcc/dccm. (See also -R) This protocol and address must match the value in sendmail.cf. This mechanism can be used to connect dccm on one computer to sendmail on another computer when a port and host name or IP address are used.

-m map

specifies a name or path of the memory mapped parameter file instead of the default /var/lib/dcc/map. It should be created with the cdcc(8) command.

-w whiteclnt

specifies an optional file containing filtering parameters as well as SMTP client IP addresses, SMTP envelope values, and header values of mail that is spam or is not spam and does not need a X-DCC header, and whose checksums should not be reported to the DCC server. If the pathname whiteclnt is not absolute, it is relative to the DCC home directory.

The format of the dccm whiteclnt file is the same as the /var/lib/dcc/whitelist files used by dbclean(8) and the whiteclnt file used by dccproc(8). See dcc(8) for a description of DCC white and blacklists. Because the contents of the whiteclnt file are used frequently, a companion file is automatically created and maintained. It has the same pathname but with an added suffix of .dccw and contains a memory mapped hash table of the main file.

A whitelist entry ("OK") or two or more semi-whitelistings ("OK2") for one of the message's checksums prevents all of the message's checksums from being reported to the DCC server and the addition of a X-DCC header line by dccm. A whitelist entry for a checksum also prevents rejecting or discarding the message based on DCC recipient counts as specified by -a and -t. Otherwise, one or more checksums with blacklisting entries ("MANY") cause all of the message's checksums to be reported to the server with an addressee count of "MANY".

If the message has a single recipient, an env_To whiteclnt entry of "OK" for the checksum of its recipient address acts like any other whiteclnt entry of "OK." When the SMTP message has more than one recipient, the effects can be complicated. When a message has several recipients with some but not all listed in the whiteclnt file, dccm tries comply with the wishes of the users who want filtering as well as those who don't by silently not delivering the message to those who want filtering (i.e. are not whitelisted) and delivering the message to users who don't want filtering.

-U userdirs

enables per-user whiteclnt files and log directories. Each target of a message can have a directory of log files named usedirs/${dcc_userdir}/log where ${dcc_userdir} is the sendmail.cf macro described below. If ${dcc_userdir} is not set, userdirs/${rcpt_mailer}/${rcpt_addr}/log is used. The most likely value of mailer is local. Appropriate values for both ${rcpt_mailer} and ${rcpt_addr} can be seen by examining env_To lines in -l logdir files. If it is not absolute, userdirs is relative to the DCC home directory. The directory containing the log files must be named log and it must be writable by the dccm process. Each log directory must exist or logging for the corresponding is silently disabled. The files created in the log directory are owned by the UID of the dccm process, but they have group and other read and write permissions copied from the corresponding log directory. To ensure the privacy of mail, it may be good to make the directories readable only by owner and group, and to use a cron script that changes the owner of each file to match the grandparent addr directory. There can also be a per-user whitelist file named userdirs/addr/whiteclnt for each addressee addr. Any checksum that is not white- or blacklisted by an individual addressee's per-user whiteclnt file is checked in the main /var/lib/dcc/whiteclnt file. A missing per-addressee whiteclnt file is the same as an empty file. Relative paths for files included in per-addressee files are resolved in the DCC home directory. The whiteclnt files and the addr directories containing them must be writable by the dccm process.

Option lines in per-user whiteclnt files can be used to modify many aspects of dccm filtering, as described in the main dcc man page. For example, an option dcc-off line turns off DCC filtering for individual mailboxes.

-a IGNORE | REJECT | DISCARD

specifies the action taken when DCC server counts or -t thresholds say that a message is unsolicited and bulk. IGNORE causes the message to be unaffected except for adding the X-DCC header line to the message. This turns off all filtering except greylisting. Spam can also be REJECTed or accepted and silently DISCARDed without being delivered to local mailboxes. The default is REJECT.

Mail forwarded via IP addresses marked MX or MXDCC in the main /var/lib/dcc/whiteclnt file is treated as if -a DISCARD were specified. This prevents "bouncing" spam.

Determinations that mail is or is not spam from sendmail via ${dcc_isspam} or ${dcc_notspam} macros override -a. The effects of the -w whiteclnt are not affected by -a.

-t type,[log-thold,]rej-thold

sets logging and "spam" thresholds for checksum type. The checksum types are IP, env_From, From, Message-ID, substitute, Received, Body, Fuz1, Fuz2, rep-total, and rep. The first six, IP through substitute, have no effect except when a local DCC server configured with -K is used. The substitute thresholds apply to the first substitute heading encountered in the mail message. The string ALL sets thresholds for all types, but is unlikely to be useful except for setting logging thresholds. The string CMN specifies the commonly used checksums Body, Fuz1, and Fuz2. Rej-thold and log-thold must be numbers, the string NEVER, or the string MANY indicating millions of targets. Counts from the DCC server as large as the threshold for any single type are taken as sufficient evidence that the message should be logged or rejected. Log-thold is the threshold at which messages are logged. It can be handy to log messages at a lower threshold to find solicited bulk mail sources such as mailing lists. If no logging threshold is set, only rejected mail and messages with complicated combinations of white and blacklisting are logged. Messages that reach at least one of their rejection thresholds are logged regardless of logging thresholds.

Rej-thold is the threshold at which messages are considered "bulk," and so should be rejected or discarded if not whitelisted.

DCC Reputation thresholds in the commercial version of DCC are controlled by thresholds on checksum types rep and rep-total. The DCC Reputations of IP addresses that the DCC database says have sent more than rep-total,log-thold are computed and messages from those addresses are logged. Messages from IP addresses with DCC Reputations of at least the rep,rej-thold rejection threshold can be rejected. The DCC Reputation of an IP address is the percentage of its messages known to have been sent to at least 10 recipients. The defaults are equivalent to rep,never and rep-total,never,20.

Bulk DCC Reputations do not reject mail unless enabled by an option DCC-rep-on line a whiteclnt file.

The checksums of locally whitelisted messages are not checked with the DCC server and so only the number of targets of the current copy of a whitelisted message are compared against the thresholds.

The default is ALL,NEVER, so that nothing is discarded, rejected, or logged. A common choice is CMN,25,50 to reject or discard mail with common bodies except as overridden by the whitelist of the DCC server, the sendmail ${dcc_isspam} and ${dcc_notspam} macros, and -g, and -w.

-g [not-]type

indicates that whitelisted, OK or OK2, counts from the DCC server for a type of checksum are to be believed. They should be ignored if prefixed with not-. Type is one of the same set of strings as for -t. Only IP, env_From, and From are likely choices. By default all three are honored, and hence the need for not-.

-S hdr

adds to the list of substitute or locally chosen headers that are checked with the -w whiteclnt file and sent to the DCC server. The checksum of the last header of type hdr found in the message is checked. Hdr can be HELO to specify the SMTP envelope HELO value. Hdr can also be mail_host to specify the host name from the Mail_from value in the SMTP envelope. As many as 8 different substitute headers can be specified, but only the checksum of the first will be sent to the DCC server.

-l logdir

specifies a directory in which files containing copies of messages processed by dccm are kept. They can be copied to per-user directories specified with -U. Information about other recipients of a message is deleted from the per-user copies. See the FILES section below concerning the contents of the files. See also the option log-subdirectory-{day,hour,minute} lines in whiteclnt files described in dcc(8).

The directory is relative to the DCC home directory if it is not absolute

-R rundir

specifies the "run" directory where the UNIX domain socket and file containing the daemon's process ID are stored. The default value is /var/run/dcc .

-r rejection-msg

specifies the rejection message for unsolicited bulk mail or for mail temporarily blocked by greylisting when -G is specified. The first -r rejection-msg replaces the default bulk mail rejection message, "5.7.1 550 mail %ID from %CIP rejected by DCC". The second replaces "4.2.1 452 mail %ID from %CIP temporary greylist embargoed". The third -r rejection-msg replaces the default SMTP rejection message "5.7.1 550 %ID bulk mail reputation; see https://commercial-dcc.rhyolite.com/cgi-bin/reps.cgi?tgt=%CIP" for mail with bulk DCC Reputations. If rejection-msg is the zero-length string, the -r setting is counted but the corresponding default message is not changed. Rejection-msg can contain specific information about the mail message. The following strings starting with % are replaced with the corresponding values:

%ID

message ID such as the unique part of log file name or sendmail queue ID

%CIP

SMTP client IP address

%BTYPE

type of DNS blacklist hit, such as "SMTP client", "mail_host", or "URL NS"

%BTGT

IP address or name declared bad by DNS blacklist

%BPROBE

domain name found in DNS blacklist such as 4.3.2.10.example.com

%BRESULT

value of the %BPROBE domain name found in DNS blacklist

A common alternate for the bulk mail rejection message is "4.7.1 451 Access denied by DCC" to tell the sending mail system to continue trying. Use a 4yz response with caution, because it is likely to delay for days a delivery failure message for false positives. If the rejection message does not start with an RFC 1893 status code and RFC 2821 reply code, 5.7.1 and 550 or 4.2.1 and 452 are used.

See also -B set:rej-msg to set the status message for mail rejected by DNS blacklists.

-j maxjobs

limits the number of simultaneous requests that will be processed. The default value is the maximum number that seems to be possible given system limits on open files, select() bit masks, and so forth. Start dccm with -d and see the starting message in the system log to see the limit.

-B dnsbl-option

enables DNS white- and blacklist checks of the SMTP client IP address, SMTP envelope Mail_From sender domain name, and of host names in URLs in the message body. Body URL blacklisting has too many false positives to use on abuse mailboxes. It is less effective than greylisting with dccm(8) or dccifd(8) but can be useful in situations where greylisting cannot be used. It can be combined with greylisting. Dnsbl-option is either one of the -B set:option forms or

```
-B
domain[any[,bltype]]
-B
domain[,IPaddr
[/xx[&IPmask][,bltype]]]
-B
domain[,IPaddrLO
[-IPaddrHI[&IPmask][,bltype]]]

```

Domain is a DNS blacklist domain such as example.com that will be searched. The strings any, IPaddr, IPaddr/xx, or IPaddrLO-IPaddrHI, specifies which IP addresses found in the DNS blacklist after applying the optional IP address mask IPmask say that mail messages should be rejected or accepted with -B set:white. "127.0.0.2" is assumed if no address(es) are specified. IPv6 addresses can be specified with the usual colon (:) notation. Host names can be used instead of numeric addresses. The type of DNS blacklist is specified by bltype as name, all-names, IPv4, or IPv6. Given an envelope sender domain name or a domain name in a URL of spam.domain.org and a blacklist of type name, spam.domain.org.example.com will be looked up. The names spam.domain.org.example.com, domain.org.example.com, and org.example.com will be looked up in blacklists of type all-names. Use name with DNS blacklists that use wildcards for speed but all-names for other DNS name blacklists. Blacklist types of IPv4 and IPv6 require that the domain name in a URL sender address be resolved into an IPv4 or IPv6 address. The resolved address from the mail message is then written as a reversed string of decimal octets to check the DNS blacklist, as in 2.0.0.127.example.com. A domain of "." and type of name can be used to blacklist domain names with specified addresses. This can be useful to detect URLs with domain names listed in a Response Policy Zone (RPZ). For example, the following can be used to reject mail containing URLs listed by a response policy zone that maps evil domain names to 224.0.0.0 with an informative status message:

```
  '-Bset:rej-msg=5.7.1 550 %ID %BTYPE \
	https://example.com/query/dbl?domain=%BTGT'
  -B.,224.0.0.0,name
```

More than one blacklist can be specified and blacklists can be grouped with -B set:group=X. All searching within a group of blacklists is stopped at the first positive result.

Unlike dccproc(8), positive results are ignored by dccm after being logged unless an option DNSBL-on or option DNSBLx-on line appears a whiteclnt file.

-B set:no-client

implies that SMTP client IP addresses and reverse DNS domain names should not be checked in the following blacklists.

-B set:client restores the default for the following blacklists.

-B set:no-mail_host

implies that SMTP envelope Mail_From sender domain names should not be checked in the following blacklists. -B set:mail_host restores the default.

-B set:no-URL

says that URLs in the message body should not be checked in the in the following blacklists. -B set:URL restores the default.

-B set:no-MX

says MX servers of sender Mail_From domain names and host names in URLs should not be checked in the following blacklists.

-B set:MX restores the default.

-B set:no-NS

says DNS servers of sender Mail_From domain names and host names in URLs should not be checked in the following blacklists. -B set:NS restores the default.

-B set:white

says the DNS list is a whitelist of names or IP addresses. -B set:black restores the default. DNS whitelist usually also need -B set:no-mail_host, -B set:no-URL, -B set:no-MX, -B set:no-NS, and -B set:no-mail_host.

-B set:defaults

is equivalent to all of -B set:black -B set:client -B set:mail_host -B set:URL -B set:MX and -B set:NS

-B set:group=X

adds following DNS blacklists specified with -B domain[...] to group 1, 2, 3, or 4.

-B set:debug=X

sets the DNS blacklist logging level

-B set:msg-secs=S

limits dccm to S seconds total for checking all DNS blacklists. The default is 25.

-B set:URL-secs=S

limits dccm to at most S seconds resolving and checking any single URL or IP address. The default is 11. Some spam contains dozens of URLs and some "spamvertised" URLs contain host names that need minutes to resolve. Busy mail systems cannot afford to spend minutes checking each incoming mail message.

-B set:rej-msg="rejection message"

sets the SMTP rejection message for the following blacklists. Rejection-msg must be in the same format as for -r. If rejection message is null, the default is restored. The default DNS blacklist rejection message is the first message set with -r.

-B set:max_helpers=X

sets maximum number of helper processes to X. In order to use typical single-threaded DNS resolver libraries, dccm uses fleets of helper processes. It is rarely a good idea to change the default, which is the same as the maximum number of simultaneous jobs set with -j.

-B set:progpath=/usr/lib/dcc/dns-helper

changes the path to the helper program.

-L ltype,facility.level

specifies how messages should be logged. Ltype must be error, info, or off to indicate which of the two types of messages are being controlled or to turn off all syslog(3) messages from dccm. Level must be a syslog(3) level among EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG. Facility must be among AUTH, AUTHPRIV, CRON, DAEMON, FTP, KERN, LPR, MAIL, NEWS, USER, UUCP, and LOCAL0 through LOCAL7. The default is equivalent to -L info,MAIL.NOTICE -L error,MAIL.ERR

dccm normally sends counts of mail rejected and so forth the to system log at midnight. The SIGUSR1 signal sends an immediate report to the system log. They will be repeated every 24 hours instead of at midnight.

## SENDMAIL MACROS
Sendmail can affect dccm with the values of some sendmail.cf macros. These macro names must be added to the Milter.macros option statements in sendmail.cf as in the example "Feature" file dcc.m4.

${dcc_isspam}

causes a mail message to be reported to the DCC server as having been addressed to "MANY" recipients. The ${dcc_isspam} macro is ignored if the ${dcc_notspam} macro is set to a non-null string If the value of the ${dcc_isspam} is null, dccm uses SMTP rejection messages controlled by -a and -r. If the value of the ${dcc_isspam} macro starts with "DISCARD", the mail message is silently discarded as with -a DISCARD. If value of the macro not null and does not start with "DISCARD", it is used as the SMTP error message given to the SMTP client trying to send the rejected message. The message starts with an optional SMTP error type and number followed by text.

The -a option does not effect messages marked spam with ${dcc_isspam}. When the ${dcc_isspam} macro is set, the message is rejected or discarded despite local or DCC database whitelist entries. The local whitelist does control whether the message's checksums will be reported to the DCC server and an X-DCC SMTP header line will be added.

${dcc_notspam}

causes a message not be considered unsolicited bulk despite evidence to the contrary. It also prevents dccm from reporting the checksums of the message to the DCC server and from adding an X-DCC header line. When the macro is set by the sendmail.cf rules, ${dcc_notspam} macros overrides DCC threshlds that say the message should be rejected as well as the effects of the ${dcc_isspam} macro.

${dcc_mail_host}

specifies the name of the SMTP client that is sending the message. This macro is usually the same as the mail_host macro. They can differ when a sendmail "smart relay" is involved. The ${dcc_mail_host} macro does not work if FEATURE(delay_checks) is used, and so dccm falls back on mail_host.

${dcc_userdir}

is the per-user whitelist and log directory for a recipient. If the macro is not set in sendmail.cf, $&{rcpt_mailer}/$&{rcpt_addr} is assumed, but with the recipient address converted to lower case. Whatever value is used, the directory name after the last slash (/) character is converted to lower case. Any value containing the string "/../" is ignored. This macro also does not work if FEATURE(delay_checks) is used.

The following two lines in a sendmail mc file have the same effect as not defining the ${dcc_userdir} macro, provided FEATURE(dcc) is also used and the sendmail cf/feature directory has a symbolic link to the /var/lib/dcc/build/dcc/misc/dcc.m4 file.

```
SLocal_check_rcpt
R$*	$: $1 $(macro {dcc_userdir} $@ $&{rcpt_mailer}/$&{rcpt_addr} $))
```

## FILES
/var/lib/dcc

is the DCC home directory.

/usr/lib/dcc/start-dccm

is a script used by /usr/lib/dcc/rcDCC to start dccm.

dcc_conf

contains parameters used by the scripts to start DCC daemons and cron jobs.

logdir

is an optional directory specified with -l and containing marked mail. Each file in the directory contains one message, at least one of whose checksums reached its -t thresholds or that is interesting for some other reason. Each file starts with lines containing the date when the message was received, the IP address of the SMTP client, and SMTP envelope values. Those lines are followed by the body of the SMTP message including its header as it was received by sendmail and without any new or changed header lines. Only approximately the first 32 KBytes of the body are recorded unless modified by ./configure --with-max-log-size=xx The checksums for the message follow the body. They are followed by lines indicating that the ${dcc_isspam} or ${dcc_notspam} sendmail.cf macros were set or one of the checksums is white- or blacklisted by the -w whiteclnt file. Each file ends with the X-DCC header line added to the message and the disposition of the message including SMTP status message if appropriate.

map

is the memory mapped file of information concerning DCC servers in the DCC home directory. See -m.

whiteclnt

contains the client whitelist in the format described in dcc(8). See -w.

whiteclnt.dccw

is a memory mapped hash table of the /var/lib/dcc/whiteclnt file.

/var/run/dcc/dccm.pid

directory contains daemon's process ID. The string “dccm” is replaced by the file name containing the daemon to facilitate running multiple daemons, probably connected to remote instances of sendmail using TCP/IP instead of a UNIX domain socket. See also -R.

/var/run/dcc/dccm

is the default UNIX domain socket used by the sendmail milter interface. See also -R.

sendmail.cf

is the sendmail(8) control file.

/var/lib/dcc/build/dcc/misc/dcc.m4

sendmail mc file that should have a symbolic link in the sendmail cf/feature directory so that FEATURE(dcc) can be used in a sendmail mc file.

## EXAMPLES
Dccm should be started before sendmail with something like the script /usr/lib/dcc/start-dccm. It looks for common DCC parameters in the /var/lib/dcc/dcc_conf file.

Those numbers should modified to fit local conditions. It might be wise to replace the "100" numbers with much larger values or with "MANY" until a few weeks of monitoring the log directory show that sources of mailing lists are in the server's whitelist file (see dccd(8)) or the local /var/lib/dcc/whiteclnt file.

It is usually necessary to regularly delete old log files with a script like /usr/lib/dcc/cron-dccd.

On systems unlike modern FreeBSD and other UNIX-like systems which include sendmail milter support, sendmail must be built with the milter interface, such as by creating a devtools/Site/site.config.m4 or similar file containing something like the following lines:

```
APPENDDEF(`conf_sendmail_ENVDEF', `-D_FFR_MILTER=1')
APPENDDEF(`conf_libmilter_ENVDEF', `-D_FFR_MILTER=1')
```

Appropriate lines invoking the milter interface must be added to sendmail.cf. That can be done by putting a symbolic link to the the misc/dcc.m4 file in the DCC source to the sendmail cf/feature directory and adding the line

FEATURE(dcc)

to the local .mc file.

Note that dccm should not be used with the Postfix milter mechanism. Instead use dccifd(8) as a before-queue filter as described in that man page.

## SEE ALSO
cdcc(8), dbclean(8), dcc(8), dccd(8), dblist(8), dccifd(8), dccproc(8), dccsight(8), sendmail(8).

## HISTORY
Distributed Checksum Clearinghouses are based on an idea of Paul Vixie. Implementation of dccm was started at Rhyolite Software in 2000. This document describes version RHYOLITE_VERSION.

## BUGS
dccm uses -t where dccproc(8) uses -c.

Systems without setrlimit(2) and getrlimit(2) RLIMIT_NOFILE can have problems with the default limit on the number of simultaneous jobs, the value of -j. Every job requires four open files. These problems are usually seen with errors messages that say something like

dccm[24448]: DCC: accept() returned invalid socket

A fix is to use a smaller value for -j or to allow dccm to open more files. Sendmail version 8.13 and later can be told to poll() instead of select with SM_CONF_POLL. Some older versions of sendmail knew about FFR_USE_POLL. One of the following lines in your devtools/Site/site.config.m4 file can help:

```
APPENDDEF(`conf_libmilter_ENVDEF', `-DSM_CONF_POLL')
APPENDDEF(`conf_libmilter_ENVDEF', `-DFFR_USE_POLL')
```

On many systems with sendmail 8.11.3 and preceding, a bug in the sendmail milter mechanism causes dccm to die with a core file when given a signal.


dccproc

package: DCC

title: dccproc(8)

text:
# dccproc(8)

## NAME
dccproc — Distributed Checksum Clearinghouse Procmail Interface

## SYNOPSIS
dccproc

[-VdAQCHEPR] [-h homedir] [-m map] [-w whiteclnt] [-T tmpdir] [-a IP-address] [-f env_from] [-t targets] [-x exitcode]

[-c type,[log-thold,]rej-thold] [-g [not-]type] [-S header]

[-i infile] [-o outfile] [-l logdir] [-B dnsbl-option] [-L ltype,facility.level]

## DESCRIPTION
Dccproc is a low performance DCC client for checking single mail messages for mail filters such as procmail(1)

Dccproc copies a complete SMTP message from standard input or a file to standard output or another file. As it copies the message, it computes the DCC checksums for the message, reports them to a DCC server, and adds a header line to the message. Another program such as procmail(1) can use the added header line to filter mail or the exit dccproc exit status.

Error messages are sent to stderr as well as the system log. Connect stderr and stdout to the same file to see errors in context, but direct stderr to /dev/null to keep DCC error messages out of the mail. The -o option can also be used to separate the error messages.

Dccproc sends reports of checksums related to mail received by DCC clients and queries about the total number of reports of particular checksums. A DCC server receives no mail, address, headers, or other information, but only cryptographically secure checksums of such information. A DCC server cannot determine the text or other information that corresponds to the checksums it receives. It only acts as a clearinghouse of counts of checksums computed by clients.

The checksums of private mail, the internal mail,and other mail that is known to not be unsolicited bulk can be listed in a whitelist specified with

When sendmail(8) is used, dccm(8) is a better DCC interface. Dccifd(8) is more efficient than dccproc because it is a daemon, but that has costs in complexity. See dccsight(8) for a way to use previously computed checksums.

### OPTIONS
The following options are available:

-V

displays the program's version. Two or more -V options show the options with which it was built.

-d

enables debugging output from the DCC client software. Additional -d options increase the number of messages. One causes error messages to be sent to STDERR as well as the system log.

-A

adds to existing X-DCC headers in the message instead of replacing existing headers of the brand of the current server.

-P

The SpamAsassin DCC.pm plugin should watch for "bulk" in X-DCC SMTP header fields, but historically has looked for counts of "many". However, there are situations when dccproc knows that a mail message is extremely bulky and probably spam. For example, mail from a sender that is blacklisted in whiteclnt gets an X-DCC header that includes bulk. To acommodate that bug in SpamAssassin, by default whenever dccproc generates an X-DCC header containing "bulk", it also forces the Body count to "many". -P turns off that kludge and the Body contains the count from the DCC server.

-Q

only queries the DCC server about the checksums of messages instead of reporting. This is useful when dccproc is used to filter mail that has already been reported to a DCC server by another DCC client. No single mail message should be reported to a DCC server more than once per recipient, because each report will increase the apparent "bulkness" of the message. It is better to use MXDCC lines in the global /var/lib/dcc/whiteclnt file for your MX mail servers that use DCC than to use -Q with dccproc.

Do not use -Q except on mail that you know has been reported to a DCC server. DCC depends on reports of all except known private mail and works only because almost no DCC installations use -Q.

-C

outputs only the X-DCC header and the checksums for the message.

-H

outputs only the X-DCC header.

-E

adds lines to the start of the log file turned on with -l and -c describing what might have been the envelope of the message. The information for the inferred envelope comes from arguments including -a and headers in the message when -R is used. No lines are generated for which no information is available, such as the envelope recipient.

-P

The SpamAsassin DCC.pm plugin should watch for "bulk" in X-DCC SMTP header fields, but historically has looked for counts of "many". However, there are situations when dccproc knows that a mail message is extremely bulky and probably spam. For example, mail from a sender that is blacklisted in whiteclnt gets an X-DCC header that includes bulk. To acommodate that bug in SpamAssassin, by default whenever dccproc generates an X-DCC header containing "bulk", it also forces the Body count to "many". -P turns off that kludge and the Body contains the count from the DCC server.

-R

says the first Received lines have the standard "helo (name [address])..." format and the address is that of the SMTP client that would otherwise be provided with -a. The -a option should be used if the local SMTP server adds a Received line with some other format or does not add a Received line. Received headers specifying IP addresses marked MX or MXDCC in the -w whiteclnt file are skipped.

-h homedir

overrides the default DCC home directory, /var/lib/dcc.

-m map

specifies a name or path of the memory mapped parameter file instead of the default /var/lib/dcc/map. It should be created with the new map operation of the cdcc(8) command.

-w whiteclnt

specifies an optional file containing SMTP client IP addresses and SMTP headers of mail that do not need X-DCC headers and whose checksums should not be reported to the DCC server. It can also contain checksums of spam. If the pathname is not absolute, it is relative to the DCC home directory. Thus, individual users with private whitelists usually specify them with absolute paths. Common whitelists shared by users must be in the DCC home directory or one of its subdirectories and owned by the set-UID user of dccproc. It is useful to include a common or system-wide whitelist in private lists. Because the contents of the whiteclnt file are used frequently, a companion file is automatically created and maintained. It has the same pathname but with an added suffix of .dccw. It contains a memory mapped hash table of the main file.

Option lines can be used to modify many aspects of dccproc filtering, as described in the main dcc(8) man page. For example, an option spam-trap-discards line turns off DCC filtering and reports the message as spam.

-T tmpdir

changes the default directory for temporary files from the system default. The system default is often /tmp.

-a IP-address

specifies the IP address (not the host name) of the immediately previous SMTP client. It is often not available. -a 0.0.0.0 is ignored. -a. The -a option should be used instead of -R if the local SMTP server adds a Received line with some other format or does not add a Received line.

-f env_from

specifies the RFC 821 envelope "Mail From" value with which the message arrived. It is often not available. If -f is not present, the contents of the first Return-Path: or UNIX style From_ header is used. The env_from string is often but need not be bracketed with "<>".

-t targets

specifies the number of addressees of the message if other than 1. The string many instead of a number asserts that there were too many addressees and that the message is unsolicited bulk email.

-x exitcode

specifies the code or status with which dccproc exits if the -c thresholds are reached or the -w whiteclnt file blacklists the message. The default value is EX_NOUSER. EX_NOUSER is 67 on many systems. Use 0 to always exit successfully.

-c type,[log-thold,]rej-thold

sets logging and "spam" thresholds for checksum type. The checksum types are IP, env_From, From, Message-ID, substitute, Received, Body, Fuz1, Fuz2, rep-total, and rep. The first six, IP through substitute, have no effect except when a local DCC server configured with -K is used. The substitute thresholds apply to the first substitute heading encountered in the mail message. The string ALL sets thresholds for all types, but is unlikely to be useful except for setting logging thresholds. The string CMN specifies the commonly used checksums Body, Fuz1, and Fuz2. Rej-thold and log-thold must be numbers, the string NEVER, or the string MANY indicating millions of targets. Counts from the DCC server as large as the threshold for any single type are taken as sufficient evidence that the message should be logged or rejected. Log-thold is the threshold at which messages are logged. It can be handy to log messages at a lower threshold to find solicited bulk mail sources such as mailing lists. If no logging threshold is set, only rejected mail and messages with complicated combinations of white and blacklisting are logged. Messages that reach at least one of their rejection thresholds are logged regardless of logging thresholds.

Rej-thold is the threshold at which messages are considered "bulk," and so should be rejected or discarded if not whitelisted.

DCC Reputation thresholds in the commercial version of DCC are controlled by thresholds on checksum types rep and rep-total. The DCC Reputations of IP addresses that the DCC database says have sent more than rep-total,log-thold are computed and messages from those addresses are logged. Messages from IP addresses with DCC Reputations of at least the rep,rej-thold rejection threshold can be rejected. The DCC Reputation of an IP address is the percentage of its messages known to have been sent to at least 10 recipients. The defaults are equivalent to rep,never and rep-total,never,20.

Bulk DCC Reputations do not reject mail unless enabled by an option DCC-rep-on line a whiteclnt file.

The checksums of locally whitelisted messages are not checked with the DCC server and so only the number of targets of the current copy of a whitelisted message are compared against the thresholds.

The default is ALL,NEVER, so that nothing is discarded, rejected, or logged. A common choice is CMN,25,50 to reject or discard mail with common bodies except as overridden by the whitelist of the DCC server, the sendmail ${dcc_isspam} and ${dcc_notspam} macros, and -g, and -w.

-g [not-]type

indicates that whitelisted, OK or OK2, counts from the DCC server for a type of checksum are to be believed. They should be ignored if prefixed with not-. Type is one of the same set of strings as for -c. Only IP, env_From, and From are likely choices. By default all three are honored, and hence the need for not-.

-S hdr

adds to the list of substitute or locally chosen headers that are checked with the -w whiteclnt file and sent to the DCC server. The checksum of the last header of type hdr found in the message is checked. Hdr can be HELO to specify the SMTP envelope HELO value. Hdr can also be mail_host to specify the host name from the Mail_from value in the SMTP envelope. As many as 8 different substitute headers can be specified, but only the checksum of the first will be sent to the DCC server.

-i infile

specifies an input file for the entire message instead of standard input. If not absolute, the pathname is interpreted relative to the directory in which dccproc was started.

-o outfile

specifies an output file for the entire message including headers instead of standard output. If not absolute, the pathname is interpreted relative to the directory in which dccproc was started.

-l logdir

specifies a directory for copies of messages whose checksum target counts exceed -c thresholds. The format of each file is affected by -E. See the FILES section below concerning the contents of the files. See also the option log-subdirectory-{day,hour,minute} lines in whiteclnt files described in dcc(8).

The directory is relative to the DCC home directory if it is not absolute

-B dnsbl-option

enables DNS white- and blacklist checks of the SMTP client IP address, SMTP envelope Mail_From sender domain name, and of host names in URLs in the message body. Body URL blacklisting has too many false positives to use on abuse mailboxes. It is less effective than greylisting with dccm(8) or dccifd(8) but can be useful in situations where greylisting cannot be used. It can be combined with greylisting. Dnsbl-option is either one of the -B set:option forms or

```
-B
domain[any[,bltype]]
-B
domain[,IPaddr
[/xx[&IPmask][,bltype]]]
-B
domain[,IPaddrLO
[-IPaddrHI[&IPmask][,bltype]]]

```

Domain is a DNS blacklist domain such as example.com that will be searched. The strings any, IPaddr, IPaddr/xx, or IPaddrLO-IPaddrHI, specifies which IP addresses found in the DNS blacklist after applying the optional IP address mask IPmask say that mail messages should be rejected or accepted with -B set:white. "127.0.0.2" is assumed if no address(es) are specified. IPv6 addresses can be specified with the usual colon (:) notation. Host names can be used instead of numeric addresses. The type of DNS blacklist is specified by bltype as name, all-names, IPv4, or IPv6. Given an envelope sender domain name or a domain name in a URL of spam.domain.org and a blacklist of type name, spam.domain.org.example.com will be looked up. The names spam.domain.org.example.com, domain.org.example.com, and org.example.com will be looked up in blacklists of type all-names. Use name with DNS blacklists that use wildcards for speed but all-names for other DNS name blacklists. Blacklist types of IPv4 and IPv6 require that the domain name in a URL sender address be resolved into an IPv4 or IPv6 address. The resolved address from the mail message is then written as a reversed string of decimal octets to check the DNS blacklist, as in 2.0.0.127.example.com. A domain of "." and type of name can be used to blacklist domain names with specified addresses. This can be useful to detect URLs with domain names listed in a Response Policy Zone (RPZ). For example, the following can be used to reject mail containing URLs listed by a response policy zone that maps evil domain names to 224.0.0.0 with an informative status message:

```
  '-Bset:rej-msg=5.7.1 550 %ID %BTYPE \
	https://example.com/query/dbl?domain=%BTGT'
  -B.,224.0.0.0,name
```

More than one blacklist can be specified and blacklists can be grouped with -B set:group=X. All searching within a group of blacklists is stopped at the first positive result.

Unlike dccm(8) and dccifd(8), no option DNSBL-on line is required in the whiteclnt file. A -B argument is sufficient to show that DNSBL filtering is wanted by the dccproc user.

-B set:no-client

implies that SMTP client IP addresses and reverse DNS domain names should not be checked in the following blacklists.

-B set:client restores the default for the following blacklists.

-B set:no-mail_host

implies that SMTP envelope Mail_From sender domain names should not be checked in the following blacklists. -B set:mail_host restores the default.

-B set:no-URL

says that URLs in the message body should not be checked in the in the following blacklists. -B set:URL restores the default.

-B set:no-MX

says MX servers of sender Mail_From domain names and host names in URLs should not be checked in the following blacklists.

-B set:MX restores the default.

-B set:no-NS

says DNS servers of sender Mail_From domain names and host names in URLs should not be checked in the following blacklists. -B set:NS restores the default.

-B set:white

says the DNS list is a whitelist of names or IP addresses. -B set:black restores the default. DNS whitelist usually also need -B set:no-mail_host, -B set:no-URL, -B set:no-MX, -B set:no-NS, and -B set:no-mail_host.

-B set:defaults

is equivalent to all of -B set:black -B set:client -B set:mail_host -B set:URL -B set:MX and -B set:NS

-B set:group=X

adds following DNS blacklists specified with -B domain[...] to group 1, 2, 3, or 4.

-B set:debug=X

sets the DNS blacklist logging level

-B set:msg-secs=S

limits dccproc to S seconds total for checking all DNS blacklists. The default is 25.

-B set:URL-secs=S

limits dccproc to at most S seconds resolving and checking any single URL or IP address. The default is 11. Some spam contains dozens of URLs and some "spamvertised" URLs contain host names that need minutes to resolve. Busy mail systems cannot afford to spend minutes checking each incoming mail message.

-L ltype,facility.level

specifies how messages should be logged. Ltype must be error, info, or off to indicate which of the two types of messages are being controlled or to turn off all syslog(3) messages from dccproc. Level must be a syslog(3) level among EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG. Facility must be among AUTH, AUTHPRIV, CRON, DAEMON, FTP, KERN, LPR, MAIL, NEWS, USER, UUCP, and LOCAL0 through LOCAL7. The default is equivalent to -L info,MAIL.NOTICE -L error,MAIL.ERR

dccproc exits with 0 on success and with the -x value if the -c thresholds are reached or the -w whiteclnt file blacklists the message. If at all possible, the input mail message is output to standard output or the -o outfile despite errors. If possible, error messages are put into the system log instead of being mixed with the output mail message. The exit status is zero for errors so that the mail message will not be rejected.

If dccproc is run more than 500 times in fewer than 5000 seconds, dccproc tries to start Dccifd(8). The attempt is made at most once per hour. Dccifd is significantly more efficient than dccproc. With luck, mechanisms such as SpamAssassin will notice when dccifd is running and switch to dccifd.

## FILES
/var/lib/dcc

DCC home directory.

map

memory mapped file in the DCC home directory of information concerning DCC servers.

whiteclnt

contains the client whitelist in the format described in dcc(8).

whiteclnt.dccw

is a memory mapped hash table corresponding to the whiteclnt file.

tmpdir

contains temporary files created and deleted as dccproc processes the message.

logdir

is an optional directory specified with -l and containing marked mail. Each file in the directory contains one message, at least one of whose checksums reached one of its -c thresholds. The entire body of the SMTP message including its header is followed by the checksums for the message.

## EXAMPLES
The following procmailrc(5) rule adds an X-DCC header to passing mail

```
:0 f
| /usr/local/bin/dccproc -ERw whiteclnt
```

This procmailrc(5) recipe rejects mail with total counts of 10 or larger for the commonly used checksums:

```
:0 fW
| /usr/local/bin/dccproc -ERw whiteclnt -ccmn,10
:0 e
{
    EXITCODE=67
    :0
    /dev/null
}
```

## SEE ALSO
cdcc(8), dcc(8), dbclean(8), dccd(8), dblist(8), dccifd(8), dccm(8), dccsight(8), mail(1), procmail(1).

## HISTORY
Distributed Checksum Clearinghouses are based on an idea of Paul Vixie. Implementation of dccproc was started at Rhyolite Software in 2000. This document describes version RHYOLITE_VERSION.

## BUGS
dccproc uses -c where dccm(8) uses -t.


dccsight

title: dccsight(8)

text:
# dccsight(8)

## NAME
dccsight — Distributed Checksum Clearinghouse raw checksum interface

## SYNOPSIS
dccsight

[-VdPQC] [-h homedir] [-m map] [-w whiteclnt] [-t targets] [-i infile] [-L ltype,facility.level]

## DESCRIPTION
Dccsight reads one or more lines containing DCC checksums, reports them to a DCC server, and writes a X-DCC header line. It can be used to report checksums obtained from dccproc(8) using -C.

### OPTIONS
The following options are available:

-V

displays the version of the DCC raw checksum interface. Two or more -V options show the options with which it was built.

-d

enables debugging output from the DCC client software. Additional -d options increase the number of messages.

-P

The SpamAsassin DCC.pm plugin should watch for "bulk" in X-DCC SMTP header fields, but historically has looked for counts of "many". However, there are situations when dccsight knows that a mail message is extremely bulky and probably spam. For example, mail from a sender that is blacklisted in whiteclnt gets an X-DCC header that includes bulk. To acommodate that bug in SpamAssassin, by default whenever dccsight generates an X-DCC header containing "bulk", it also forces the Body count to "many". -P turns off that kludge and the Body contains the count from the DCC server.

-Q

only queries the DCC server about the checksums of messages instead of reporting. This is useful when dccsight is used to filter mail that has already been reported to a DCC server by another DCC client. No single mail message should be reported to a DCC server more than once per recipient, because each report will increase the apparent "bulkness" of the message. It is better to use MXDCC lines in the global /var/lib/dcc/whiteclnt file for your MX mail servers that use DCC than to use -Q with dccsight.

Do not use -Q except on mail that you know has been reported to a DCC server. DCC depends on reports of all except known private mail and works only because almost no DCC installations use -Q.

-C

outputs the checksums for the message as well as the X-DCC header.

-h homedir

overrides the default DCC home directory, /var/lib/dcc.

-m map

specifies a name or path of the memory mapped parameter file instead of the default /var/lib/dcc/map in the DCC home directory. It should be created with the cdcc(8) command.

-w whiteclnt

specifies an optional file containing SMTP client IP addresses and SMTP headers of mail that do not need X-DCC headers and whose checksums should not be reported to the DCC server. It can also contain checksums of spam. If the pathname is not absolute, it is relative to the DCC home directory. Thus, individual users with private whitelists usually specify them with absolute paths. It is useful to include a common or system-wide whitelist in private lists. The format of the dccsight whiteclnt file is the same as the /var/lib/dcc/whitelist file required by dbclean(8) and dccsight(8). Because this list is used frequently, a companion file is used. It has the same pathname but with an added suffix of .dccw. After being created empty, it will contain an automatic memory mapped hash table of the main file.

-t targets

specifies the number of addressees of the message if other than 1. The string many instead of a number asserts that there were too many addressees and that the message is unsolicited bulk email.

-i infile

specifies an input file instead of standard input. If not absolute, the pathname is interpreted relative to the directory in which dccsight was started.

-L ltype,facility.level

specifies how messages should be logged. Ltype must be error, info, or off to indicate which of the two types of messages are being controlled or to turn off all syslog(3) messages from dccsight. Level must be a syslog(3) level among EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG. Facility must be among AUTH, AUTHPRIV, CRON, DAEMON, FTP, KERN, LPR, MAIL, NEWS, USER, UUCP, and LOCAL0 through LOCAL7. The default is equivalent to -L info,MAIL.NOTICE -L error,MAIL.ERR

dccsight exits 0 on success, and >0 if an error occurs.

## FILES
/var/lib/dcc

DCC home directory.

map

memory mapped file in the DCC home directory of information concerning DCC servers.

whiteclnt

contains the client whitelist in the format described in dcc(8).

whiteclnt.dccw

memory mapped hash table of the /var/lib/dcc/whiteclnt file.

## SEE ALSO
cdcc(8), dcc(8), dbclean(8), dccd(8), dblist(8), dccproc(8), dccm(8), dccifd(8), mail(1), procmail(1).

## HISTORY
Implementation of dccsight was started at Rhyolite Software in 2000. This document describes version RHYOLITE_VERSION.


MAKEDEV

package: MAKEDEV

title: MAKEDEV(8)

summary: create devices

text:
# MAKEDEV(8)

## NAME
MAKEDEV - create devices

## SYNOPSIS
cd dev; ./MAKEDEV -V

cd dev; ./MAKEDEV [ -d directory ] [ -c configdir ] [ -m maxdevices ] [-n] [-v] [-i] [-M] [-S] device ...

## DESCRIPTION
MAKEDEV is a program that will create the devices in /dev used to interface with drivers in the kernel.

Note that programs giving the error ``ENOENT: No such file or directory'' normally means that the device file is missing, whereas ``ENODEV: No such device'' normally means the kernel does not have the driver configured or loaded.

## OPTIONS
-V

Print out version and exit.

-n

Do not actually update the devices, just print the actions that would be performed.

-M

Create symlinks, directories, and sockets belonging to the current user, and print out the list of devices which would be created in a format which is understood by RPM.

-S

Do not actually update the devices, just print the actions that would be performed in a format which can be fed to a shell.

-d directory

Create the devices under directory instead of the default (usually /dev).

-v

Be verbose. Print out the actions as they are performed. This is the same output as produced by the -n option.

-i

Ignore errors parsing configuration files.

## CUSTOMIZATION
Since there is currently no standardization in what names are used for system users and groups, it is possible that you may need to modify MAKEDEV's configuration files to reflect your site's settings.

## DEVICES
Certain devices are required for minimal functionality. These are:

mem - access to physical memory; kmem - access to kernel virtual memory; null - null device (infinite sink); port - access to I/O ports; zero - null byte source (infinite source); core - symlink to /proc/kcore (for kernel debugging); full - always returns ENOSPACE on write; ram - ramdisk; tty - to access the controlling tty of a process.

Virtual Terminals

console

This creates the devices associated with the console. These are the virtual terminals ttyx, where x can be from 0 though 63. The device tty0 is the currently active VT, and is also known as console. For each VT, there are two devices: vcsx and vcsax, which can be used to generate screen-dumps of the VT (vcsx is just the text, and vcsax includes the attributes).

Serial Devices

ttyS{0..63}

Serial ports.

Pseudo Terminals

pty[p-s]

Each possible argument will create a bank of 16 master and slave pairs. The current kernel (1.2) is limited to 64 such pairs. The master pseudo-terminals are pty[p-s][0-9a-f], and the slaves are tty[p-s][0-9a-f].

Parallel Ports

lp

Standard parallel ports. The devices are created lp0, lp1, and lp2.

Bus Mice

busmice

The various bus mice devices. This creates the following devices: logimouse (Logitech bus mouse), psmouse (PS/2-style mouse), msmouse (Microsoft Inport bus mouse) and atimouse (ATI XL bus mouse) and jmouse (J-mouse).

Joystick Devices

js

Joystick. Creates js0 and js1.

Disk Devices

fd[0-7]

Floppy disk devices. The device fdx is the device which autodetects the format, and the additional devices are fixed format (whose size is indicated in the name). The other devices are named as fdxLn. The single letter L identifies the type of floppy disk (d = 5.25" DD, h = 5.25" HD, D = 3.5" DD, H = 3.5" HD, E = 3.5" ED). The number n represents the capacity of that format in K. Thus the standard formats are fdxd360, fdxh1200, fdxD720, fdxH1440, and fdxE2880.

For more information see Alain Knaff's fdutils package.

Devices fd0* through fd3* are floppy disks on the first controller, and devices fd4* through fd7* are floppy disks on the second controller.

hd[a-d]

AT hard disks. The device hdx provides access to the whole disk, with the partitions being hdx[0-20]. The four primary partitions are hdx1 through hdx4, with the logical partitions being numbered from hdx5 though hdx20. (A primary partition can be made into an extended partition, which can hold 4 logical partitions). By default, only the devices for 4 logical partitions are made. The others can be made by uncommenting them.

Drives hda and hdb are the two on the first controller. If using the new IDE driver (rather than the old HD driver), then hdc and hdd are the two drives on the secondary controller. These devices can also be used to acess IDE CDROMs if using the new IDE driver.

xd[a-d]

XT hard disks. Partitions are the same as IDE disks.

sd[a-z], sd[a-c][a-z], sdd[a-x]

SCSI hard disks. The partitions are similar to the IDE disks, but there is a limit of 11 logical partitions (sdx5 through sdx15). This is to allow there to be 128 SCSI disks.

loop

Loopback disk devices. These allow you to use a regular file as a block device. This means that images of filesystems can be mounted, and used as normal. This creates 16 devices loop0 through loop15.

Tape Devices

st[0-7]

SCSI tapes. This creates the rewinding tape device stx and the non-rewinding tape device nstx.

qic

QIC-80 tapes. The devices created are rmt8, rmt16, tape-d, and tape-reset.

ftape

Floppy driver tapes (QIC-117). There are 4 methods of access depending on the floppy tape drive. For each of access methods 0, 1, 2 and 3, the devices rftx (rewinding) and nrftx (non-rewinding) are created. For compatability, devices ftape and nftape are symlinks to rft0 and nrft0 respectively.

CDROM Devices

scd[0-7]

SCSI CD players.

sonycd

Sony CDU-31A CD player.

mcd

Mitsumi CD player.

cdu535

Sony CDU-535 CD player.

lmscd

LMS/Philips CD player.

sbpcd{,1,2,3}

Sound Blaster CD player. The kernel is capable of supporting 16 CDROMs, each of which is accessed as sbpcd[0-9a-f]. These are assigned in groups of 4 to each controller. sbpcd is a symlink to sbpcd0.

Scanner

logiscan

Logitech ScanMan32 & ScanMan 256.

m105scan

Mustek M105 Handscanner.

ac4096

A4Tek Color Handscanner.

Audio

sound

This creates the audio devices used by the sound driver. These include mixer, sequencer, dsp, and audio.

Miscellaneous

sg

Generic SCSI devices. The devices created are sga through sgh and sg0 through sg7. These allow arbitary commands to be sent to any SCSI device. This allows for querying information about the device, or controlling SCSI devices that are not one of disk, tape or CDROM (e.g. scanner, CD-R, CD-RW).

fd

To allow an arbitary program to be fed input from file descriptor x, use /dev/fd/x as the file name. This also creates /dev/stdin, /dev/stdout, and /dev/stderr. (Note, these are just symlinks into /proc/self/fd).

ibcs2

Devices (and symlinks) needed by the IBCS2 emulation.

apm

Devices for power management.

Network Devices

Linux used to have devices in /dev for controlling network devices, but that is no longer the case. To see what network devices are known by the kernel, look in /proc/net/dev.

Other Devices

Note that the list of devices above is not exhaustive. MAKEDEV can create more devices nodes. Its aim is to be able to create everything listed in the devices.txt file distributed with Linux 2.4.

## CONFIGURATION
MAKEDEV doesn't actually know anything about devices. It reads all of the information from files stored in /etc/makedev.d. MAKEDEV will read any and all files in the subdirectory, processing lines in them like so:

devices

[b|c] mode owner group major minor inc count fmt [base]

count devices will be created, with permissions set to mode and owned by owner and group. The first device will be named fmt, and additional devices will be created if count is larger than 1. If fmt contains a C-style formatting string, it will be filled with the sum of base and zero. Subsequent devices will be filled with the sum of base and n * inc, where n is the order this device is being created in. If the format string did not already include a format specifier, a "%d" will automatically be appended to it to make this work.

symbolic links

l linkname target

A symbolic link pointing to target named linkname will be created.

aliases

a alias value

Any commands that create devices for alias will also include devices that would be crated for value.

## SEE ALSO
Linux Allocated Devices, maintained by H. Peter Anvin, <Peter.Anvin@linux.org>.

## BUGS
Let's hope not. If we're lucky, any problems we'll find will be confined to the configuration files, which were written by examining the devices.txt file.

## AUTHOR
Nalin Dahyabhai, based largely on work done by Nick Holloway and Michael K. Johnson.


ModemManager

package: ModemManager

title: ModemManager(8)

text:
# ModemManager(8)

## NAME
ModemManager - mobile broadband modem management daemon

## SYNOPSIS
ModemManager [OPTION...]

## DESCRIPTION
ModemManager provides a unified high level API for communicating with mobile broadband modems, regardless of the protocol used to communicate with the actual device (Generic AT, vendor-specific AT, QCDM, QMI, MBIM...).

ModemManager is a DBus-based system daemon and is not meant to be used directly from the command line.

## APPLICATION OPTIONS
--filter-policy=<policy>

Specify which ports are probed and how:

'ALLOWLIST-ONLY'

Only devices or ports explicitly allowlisted with the 'ID_MM_DEVICE_PROCESS' udev tag are probed.

'STRICT'

Only the TTY ports that are heuristically determined to be very likely to be modem ports are probed. Nay end up ignoring some devices.

--no-auto-scan

Fully disable udev-based auto-scan looking for devices.

--initial-kernel-events=<filename>

Specify location of the file where the list of initial kernel events is available. The ModemManager daemon will process this file on startup.

--debug

Runs ModemManager with "DEBUG" log level and without daemonizing. This is useful for debugging, as it directs log output to the controlling terminal in addition to syslog.

-V, --version

Print the ModemManager software version and exit.

-h, --help

Show application options.

## LOGGING OPTIONS
--log-level=<level>

Sets how much information ModemManager sends to the log destination (usually syslog's "daemon" facility). By default, only informational, warning, and error messages are logged. Given level must be one of "ERR", "WARN", "INFO" or "DEBUG".

--log-file=<filename>

Specify location of the file where ModemManager will dump its log messages, instead of syslog.

--log-journal

Output log message to the systemd journal.

--log-timestamps

Include absolute timestamps in the log output.

--log-relative-timestamps

Include timestamps, relative to the start time of the daemon, in the log output.

## TEST OPTIONS
--test-session

Run the ModemManager daemon in the Session bus instead of the System bus.

--test-enable

Enable the Test DBus interface in the daemon.

--test-plugin-dir=[PATH]

Specify an alternate directory where the daemon should look for vendor plugins.

## AUTHOR
Aleksander Morgado <aleksander@aleksander.es>

## SEE ALSO
mmcli(1), NetworkManager(8)


mysqld

package: MySQL-server

title: mysqld(8)

summary: the MySQL server

text:
# mysqld(8)

## NAME
mysqld - the MySQL server

## SYNOPSIS
mysqld [options]

## DESCRIPTION
mysqld, also known as MySQL Server, is a single multithreaded program that does most of the work in a MySQL installation. It does not spawn additional processes. MySQL Server manages access to the MySQL data directory that contains databases and tables. The data directory is also the default location for other information such as log files and status files.

Note

Some installation packages contain a debugging version of the server named mysqld-debug. Invoke this version instead of mysqld for debugging support, memory allocation checking, and trace file support (see Section 7.9.1.2, “Creating Trace Files”).

When MySQL server starts, it listens for network connections from client programs and manages access to databases on behalf of those clients.

The mysqld program has many options that can be specified at startup. For a complete list of options, run this command:

```
mysqld --verbose --help
```

MySQL Server also has a set of system variables that affect its operation as it runs. System variables can be set at server startup, and many of them can be changed at runtime to effect dynamic server reconfiguration. MySQL Server also has a set of status variables that provide information about its operation. You can monitor these status variables to access runtime performance characteristics.

For a full description of MySQL Server command options, system variables, and status variables, see Section 7.1, “The MySQL Server”. For information about installing MySQL and setting up the initial configuration, see Chapter 2, Installing MySQL.

## COPYRIGHT
Copyright © 1997, 2025, Oracle and/or its affiliates.

This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.

## SEE ALSO
For more information, please refer to the MySQL Reference Manual, which may already be installed locally and which is also available online at http://dev.mysql.com/doc/.

## AUTHOR
Oracle Corporation (http://dev.mysql.com/).


nm-cloud-setup

package: NetworkManager-cloud-setup

title: nm-cloud-setup(8)

text:
# nm-cloud-setup(8)

## NAME
nm-cloud-setup - Overview of Automatic Network Configuration in Cloud

## OVERVIEW
When running a virtual machine in a public cloud environment, it is desirable to automatically configure the network of that VM. In simple setups, the VM only has one network interface and the public cloud supports automatic configuration via DHCP, DHCP6 or IPv6 autoconf. However, the virtual machine might have multiple network interfaces, or multiple IP addresses and IP subnets on one interface which cannot be configured via DHCP. Also, the administrator may reconfigure the network while the machine is running. NetworkManager's nm-cloud-setup is a tool that automatically picks up such configuration in cloud environments and updates the network configuration of the host.

Multiple cloud providers are supported. See the section called “SUPPORTED CLOUD PROVIDERS”.

## USE
The goal of nm-cloud-setup is to be configuration-less and work automatically. All you need is to opt-in to the desired cloud providers (see the section called “ENVIRONMENT VARIABLES”) and run /usr/libexec/nm-cloud-setup.

Usually this is done by enabling the nm-cloud-setup.service systemd service and let it run periodically. For that there is both a nm-cloud-setup.timer systemd timer and a NetworkManager dispatcher script.

## DETAILS
nm-cloud-setup configures the network by fetching the configuration from the well-known meta data server of the cloud provider. That means, it already needs the network configured to the point where it can reach the meta data server. Commonly that means, that a simple connection profile is activated that possibly uses DHCP to get the primary IP address. NetworkManager will create such a profile for ethernet devices automatically if it is not configured otherwise via "no-auto-default" setting in NetworkManager.conf. One possible alternative may be to create such an initial profile with nmcli device connect "$DEVICE" or nmcli connection add type ethernet ....

By setting the user-data org.freedesktop.nm-cloud-setup.skip=yes on the profile, nm-cloud-setup will skip the device.

nm-cloud-setup modifies the run time configuration akin to nmcli device modify. With this approach, the configuration is not persisted and only preserved until the device disconnects.

### /usr/libexec/nm-cloud-setup
The binary /usr/libexec/nm-cloud-setup does most of the work. It supports no command line arguments but can be configured via environment variables. See the section called “ENVIRONMENT VARIABLES” for the supported environment variables.

By default, all cloud providers are disabled unless you opt-in by enabling one or several providers. If cloud providers are enabled, the program tries to fetch the host's configuration from a meta data server of the cloud via HTTP. If configuration could be not fetched, no cloud provider are detected and the program quits. If host configuration is obtained, the corresponding cloud provider is successfully detected. Then the network of the host will be configured.

It is intended to re-run nm-cloud-setup every time when the configuration (maybe) changes. The tool is idempotent, so it should be OK to also run it more often than necessary. You could run /usr/libexec/nm-cloud-setup directly. However it may be preferable to restart the nm-cloud-setup systemd service instead or use the timer or dispatcher script to run it periodically (see below).

### nm-cloud-setup.service systemd unit
Usually /usr/libexec/nm-cloud-setup is not run directly, but only by systemctl restart nm-cloud-setup.service. This ensures that the tool only runs once at any time. The unit is also used by the nm-cloud-setup systemd timer and allows enabling/disabling the service via systemd.

As you need to set environment variable to configure nm-cloud-setup binary, you can do so via systemd override files. Try systemctl edit nm-cloud-setup.service.

### nm-cloud-setup.timer systemd timer
/usr/libexec/nm-cloud-setup is intended to run whenever an update is necessary. For example, during boot when when changing the network configuration of the virtual machine via the cloud provider.

One way to do this, is by enabling the nm-cloud-setup.timer systemd timer with systemctl enable --now nm-cloud-setup.timer.

### /usr/lib/NetworkManager/dispatcher.d/90-nm-cloud-setup.sh
There is also a NetworkManager dispatcher script that will run for example when an interface is activated by NetworkManager. Together with the nm-cloud-setup.timer systemd timer this script is to automatically pick up changes to the network.

The dispatcher script will do nothing, unless the systemd service is enabled. To use the dispatcher script you should therefor run systemctl enable nm-cloud-setup.service once.

## ENVIRONMENT VARIABLES
The following environment variables are used to configure /usr/libexec/nm-cloud-setup. You may want to configure them with a drop-in for the systemd service. For example by calling systemctl edit nm-cloud-setup.service and configuring [Service] Environment=, as described in systemd.exec(5) manual.

•NM_CLOUD_SETUP_LOG: control the logging verbosity. Set it to one of TRACE, DEBUG, INFO, WARN, ERR or OFF. The program will print message on stdout and the default level is WARN. When run as systemd service, the log will be collected by journald can can be seen with journalctl.

•NM_CLOUD_SETUP_AZURE: boolean, whether Microsoft Azure support is enabled. Defaults to no.

•NM_CLOUD_SETUP_EC2: boolean, whether Amazon EC2 (AWS) support is enabled. Defaults to no.

•NM_CLOUD_SETUP_GCP: boolean, whether Google GCP support is enabled. Defaults to no.

•NM_CLOUD_SETUP_ALIYUN: boolean, whether Alibaba Cloud (Aliyun) support is enabled. Defaults to no.

•NM_CLOUD_SETUP_OCI: boolean, whether Oracle Cloud (OCI) support is enabled. Defaults to no.

## DEBUGGING
Enable debug logging by setting NM_CLOUD_SETUP_LOG environment variable to TRACE.

In the common case where nm-cloud-setup is running as systemd service, this can be done via systemctl edit nm-cloud-setup.service and add Environment=NM_CLOUD_SETUP_LOG=TRACE to the [Service] section. Afterwards, the log can be found in syslog via journalctl. You may also want to enable debug logging in NetworkManager as descibed in the DEBUGGING section in NetworkManager(5) manual. When sharing logs, it's best to share complete logs and not preemptively filter for NetworkManager or nm-cloud-setup logs.

## EXAMPLE SETUP FOR CONFIGURING AND PREDEPLOYING NM-CLOUD-SETUP
As detailed before, nm-cloud-setup needs to be explicitly enabled. As it runs as a systemd service and timer, that basically means to enable and configure those. This can be done by dropping the correct files and symlinks to disk.

The following example enables nm-cloud-setup for Amazon EC2 cloud:

```
dnf install -y NetworkManager-cloud-setup
mkdir -p /etc/systemd/system/nm-cloud-setup.service.d
cat > /etc/systemd/system/nm-cloud-setup.service.d/10-enable-ec2.conf << EOF
[Service]
Environment=NM_CLOUD_SETUP_EC2=yes
EOF
# systemctl enable nm-cloud-setup.service
mkdir -p /etc/systemd/system/NetworkManager.service.wants/
ln -s /usr/lib/systemd/system/nm-cloud-setup.service /etc/systemd/system/NetworkManager.service.wants/nm-cloud-setup.service
# systemctl enable nm-cloud-setup.timer
mkdir -p /etc/systemd/system/timers.target.wants/
ln -s /etc/systemd/system/timers.target.wants/nm-cloud-setup.timer /usr/lib/systemd/system/nm-cloud-setup.timer
# systemctl daemon-reload

```

## SUPPORTED CLOUD PROVIDERS

### Amazon EC2 (AWS)
For AWS, the tools tries to fetch configuration from http://169.254.169.254/. Currently, it only configures IPv4 and does nothing about IPv6. It will do the following.

•First fetch http://169.254.169.254/latest/meta-data/ to determine whether the expected API is present. This determines whether EC2 environment is detected and whether to proceed to configure the host using EC2 meta data.

•Fetch http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/ to get the list of available interface. Interfaces are identified by their MAC address.

•Then for each interface fetch http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/$MAC/subnet-ipv4-cidr-block and http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/$MAC/local-ipv4s. Thereby we get a list of local IPv4 addresses and one CIDR subnet block.

•Then nm-cloud-setup iterates over all interfaces for which it could fetch IP configuration. If no ethernet device for the respective MAC address is found, it is skipped. Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user-data org.freedesktop.nm-cloud-setup.skip=yes, it is skipped. If only one interface and one address is configured, then the tool does nothing and leaves the automatic configuration that was obtained via DHCP.

Otherwise, the tool will change the runtime configuration of the device.

•Add static IPv4 addresses for all the configured addresses from local-ipv4s with prefix length according to subnet-ipv4-cidr-block. For example, we might have here 2 IP addresses like "172.16.5.3/24,172.16.5.4/24".

•Choose a route table 30400 + the index of the interface and add a default route 0.0.0.0/0. The gateway is the first IP address in the CIDR subnet block. For example, we might get a route "0.0.0.0/0 172.16.5.1 10 table=30400". Also choose a route table 30200 + the interface index. This contains a direct routes to the subnets of this interface.

•Finally, add a policy routing rule for each address. For example "priority 30200 from 172.16.5.3/32 table 30200, priority 30200 from 172.16.5.4/32 table 30200". and "priority 30400 from 172.16.5.3/32 table 30400, priority 30400 from 172.16.5.4/32 table 30400" The 30200+ rules select the table to reach the subnet directly, while the 30400+ rules use the default route. Also add a rule "priority 30350 table main suppress_prefixlength 0". This has a priority between the two previous rules and causes a lookup of routes in the main table while ignoring the default route. The purpose of this is so that other specific routes in the main table are honored over the default route in table 30400+.

With above example, this roughly corresponds for interface eth0 to nmcli device modify "eth0" ipv4.addresses "172.16.5.3/24,172.16.5.4/24" ipv4.routes "172.16.5.0/24 0.0.0.0 10 table=30200, 0.0.0.0/0 172.16.5.1 10 table=30400" ipv4.routing-rules "priority 30200 from 172.16.5.3/32 table 30200, priority 30200 from 172.16.5.4/32 table 30200, priority 20350 table main suppress_prefixlength 0, priority 30400 from 172.16.5.3/32 table 30400, priority 30400 from 172.16.5.4/32 table 30400". Note that this replaces the previous addresses, routes and rules with the new information. But also note that this only changes the run time configuration of the device. The connection profile on disk is not affected.

### Google Cloud Platform (GCP)
For GCP, the meta data is fetched from URIs starting with http://metadata.google.internal/computeMetadata/v1/ with a HTTP header "Metadata-Flavor: Google". Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following.

•First fetch http://metadata.google.internal/computeMetadata/v1/instance/id to detect whether the tool runs on Google Cloud Platform. Only if the platform is detected, it will continue fetching the configuration.

•Fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/ to get the list of available interface indexes. These indexes can be used for further lookups.

•Then, for each interface fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/mac to get the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on.

•Then, for each interface with a MAC address fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/ and then all the found IP addresses at http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/$FIPS_INDEX.

•At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses. For each device, we lookup the currently applied connection in NetworkManager. That implies, that the device is currently activated in NetworkManager. If no such device was in NetworkManager, or if the profile has user-data org.freedesktop.nm-cloud-setup.skip=yes, we skip the device. Now for each found IP address we add a static route "$FIPS_ADDR/32 0.0.0.0 100 type=local" and reapply the change.

The effect is not unlike calling nmcli device modify "$DEVICE" ipv4.routes "$FIPS_ADDR/32 0.0.0.0 100 type=local [,...]" for all relevant devices and all found addresses.

### Microsoft Azure
For Azure, the meta data is fetched from URIs starting with http://169.254.169.254/metadata/instance with a URL parameter "?format=text&api-version=2017-04-02" and a HTTP header "Metadata:true". Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following.

•First fetch http://169.254.169.254/metadata/instance?format=text&api-version=2017-04-02 to detect whether the tool runs on Azure Cloud. Only if the platform is detected, it will continue fetching the configuration.

•Fetch http://169.254.169.254/metadata/instance/network/interface/?format=text&api-version=2017-04-02 to get the list of available interface indexes. These indexes can be used for further lookups.

•Then, for each interface fetch http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/macAddress?format=text&api-version=2017-04-02 to get the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on.

•Then, for each interface with a MAC address fetch http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/?format=text&api-version=2017-04-02 to get the list of (indexes of) IP addresses on that interface.

•Then, for each IP address index fetch the address at http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/$ADDR_INDEX/privateIpAddress?format=text&api-version=2017-04-02. Also fetch the size of the subnet and prefix for the interface from http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/address/?format=text&api-version=2017-04-02. and http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/prefix/?format=text&api-version=2017-04-02.

•At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses. Then the tool configures the system like doing for AWS environment. That is, using source based policy routing with the tables/rules 30200/30400.

### Alibaba Cloud (Aliyun)
For Aliyun, the tools tries to fetch configuration from http://100.100.100.200/. Currently, it only configures IPv4 and does nothing about IPv6. It will do the following.

•First fetch http://100.100.100.200/2016-01-01/meta-data/ to determine whether the expected API is present. This determines whether Aliyun environment is detected and whether to proceed to configure the host using Aliyun meta data.

•Fetch http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/ to get the list of available interface. Interfaces are identified by their MAC address.

•Then for each interface fetch http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/vpc-cidr-block, http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/private-ipv4s, http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/netmask and http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/gateway. Thereby we get a list of private IPv4 addresses, one CIDR subnet block and private IPv4 addresses prefix.

•Then nm-cloud-setup iterates over all interfaces for which it could fetch IP configuration. If no ethernet device for the respective MAC address is found, it is skipped. Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user-data org.freedesktop.nm-cloud-setup.skip=yes, it is skipped. Also, there is only one interface and one IP address, the tool does nothing. Then the tool configures the system like doing for AWS environment. That is, using source based policy routing with the tables/rules 30200/30400. One difference to AWS is that the gateway is also fetched via metadata instead of using the first IP address in the subnet.

### Oracle Cloud (OCI)
For OCI, the tools tries to fetch configuration from http://169.254.169.254/. Currently, it only configures IPv4 and does nothing about IPv6. It will do the following.

•First fetch http://169.254.169.254/opc/v2/instance to determine whether the expected API is present. This determines whether OCI environment is detected and whether to proceed to configure the host using OCI meta data.

•Fetch http://169.254.169.254/opc/v2/vnics to get the configuration for all the VNICs, getting their MAC address, private IP address, gateway and subnet block.

•Then nm-cloud-setup iterates over all interfaces for which it could fetch a configuration. If no ethernet device for the respective MAC address is found, it is skipped. Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user-data org.freedesktop.nm-cloud-setup.skip=yes, it is skipped. Also, there is only one interface and one IP address, the tool does nothing. Then the tool configures the system like doing for AWS environment. That is, using source based policy routing with the tables/rules 30200/30400.

## SEE ALSO
NetworkManager(8) nmcli(1)


NetworkManager

package: NetworkManager-daemon

title: NetworkManager(8)

summary: network management daemon

text:
# NetworkManager(8)

## NAME
NetworkManager - network management daemon

## SYNOPSIS
NetworkManager [OPTIONS...]

## DESCRIPTION
The NetworkManager daemon attempts to make networking configuration and operation as painless and automatic as possible by managing the primary network connection and other network interfaces, like Ethernet, Wi-Fi, and Mobile Broadband devices. NetworkManager will connect any network device when a connection for that device becomes available, unless that behavior is disabled. Information about networking is exported via a D-Bus interface to any interested application, providing a rich API with which to inspect and control network settings and operation.

## DISPATCHER SCRIPTS
NetworkManager-dispatcher service can execute scripts for the user in response to network events. See NetworkManager-dispatcher(8) manual.

## OPTIONS
The following options are understood:

--version | -V

Print the NetworkManager software version and exit.

--help | -h

Print NetworkManager's available options and exit.

--no-daemon | -n

Do not daemonize.

--debug | -d

Do not daemonize, and direct log output to the controlling terminal in addition to syslog.

--pid-file | -p

Specify location of a PID file. The PID file is used for storing PID of the running process and prevents running multiple instances.

--state-file

Specify file for storing state of the NetworkManager persistently. If not specified, the default value of /var/lib/NetworkManager/NetworkManager.state is used.

--config

Specify configuration file to set up various settings for NetworkManager. If not specified, the default value of /etc/NetworkManager/NetworkManager.conf is used with a fallback to the older 'nm-system-settings.conf' if located in the same directory. See NetworkManager.conf(5) for more information on configuration file.

--configure-and-quit [initrd]

Quit after all devices reach a stable state. The optional initrd parameter enables mode, where no processes are left running after NetworkManager stops, which is useful for running from an initial ramdisk on rearly boot.

--plugins

List plugins used to manage system-wide connection settings. This list has preference over plugins specified in the configuration file. See main.plugins setting in NetworkManager.conf(5) for supported options.

--log-level

Sets how much information NetworkManager sends to the log destination (usually syslog's "daemon" facility). By default, only informational, warning, and error messages are logged. See the section on logging in NetworkManager.conf(5) for more information.

--log-domains

A comma-separated list specifying which operations are logged to the log destination (usually syslog). By default, most domains are logging-enabled. See the section on logging in NetworkManager.conf(5) for more information.

--print-config

Print the NetworkManager configuration to stdout and exit. See NetworkManager.conf(5). This does not include connection profiles. View them with nmcli connection. This reads configuration files from disk. If NetworkManager is currently running, make sure that it has the same configuration loaded.

## UDEV PROPERTIES
udev(7) device manager is used for the network device discovery. The following property influences how NetworkManager manages the devices:

NM_UNMANAGED

If set to "1" or "true", the device is configured as unmanaged by NetworkManager. Note that the user still can explicitly overrule this configuration via means like nmcli device set "$DEVICE" managed yes or "device*.managed=1" in NetworkManager.conf.

ID_NET_MANAGED_BY

If NM_UNMANAGED is set, this has no effect. Otherwise, if the attribute is set to anything but "org.freedesktop.NetworkManager", the device is unmanaged.

NM_AUTO_DEFAULT_LINK_LOCAL_ONLY

If set to "1" or "true", the automatically generated connections "Wired connection N" will only enable link local addressing for IPv4 and IPv6. This can be useful on thunderbolt devices or host-to-host USB devices.

ID_NET_AUTO_LINK_LOCAL_ONLY

Honored and treated the same as if NM_AUTO_DEFAULT_LINK_LOCAL_ONLY were set.

ID_NET_DHCP_BROADCAST

If set to "1" or "true", use broadcast requests for DHCPv4 offers. This can make sense of devices that can't handle unicast messages until being configured.

## SIGNALS
NetworkManager process handles the following signals:

SIGHUP

The signal causes a reload of NetworkManager's configuration. Note that not all configuration parameters can be changed at runtime and therefore some changes may be applied only after the next restart of the daemon. A SIGHUP also involves further reloading actions, like doing a DNS update and restarting the DNS plugin. The latter can be useful for example when using the dnsmasq plugin and changing its configuration in /etc/NetworkManager/dnsmasq.d. However, it also means this will shortly interrupt name resolution. In the future, there may be further actions added. A SIGHUP means to update NetworkManager configuration and reload everything that is supported. Note that this does not reload connections from disk. For that there is a D-Bus API and nmcli's reload action

SIGUSR1

The signal forces a rewrite of DNS configuration. Contrary to SIGHUP, this does not restart the DNS plugin and will not interrupt name resolution. When NetworkManager is not managing DNS, the signal forces a restart of operations that depend on the DNS configuration (like the resolution of the system hostname via reverse DNS, or the resolution of WireGuard peers); therefore, it can be used to tell NetworkManager that the content of resolv.conf was changed externally. In the future, further actions may be added. A SIGUSR1 means to write out data like resolv.conf, or refresh a cache. It is a subset of what is done for SIGHUP without reloading configuration from disk.

SIGUSR2

The signal has no effect at the moment but is reserved for future use.

An alternative to a signal to reload configuration is the Reload D-Bus call. It allows for more fine-grained selection of what to reload, it only returns after the reload is complete, and it is guarded by PolicyKit.

## DEBUGGING
NetworkManager only configures your system. So when your networking setup doesn't work as expected, the first step is to look at your system to understand what is actually configured, and whether that is correct. The second step is to find out how to tell NetworkManager to do the right thing.

You can for example try to ping hosts (by IP address or DNS name), look at ip link show, ip address show and ip route show, and look at /etc/resolv.conf for name resolution issues. Also look at the connection profiles that you have configured in NetworkManager (nmcli connection and nmcli connection show "$PROFILE") and the configured interfaces (nmcli device).

If that does not suffice, look at the logfiles of NetworkManager. NetworkManager logs to syslog, so depending on your system configuration you can call journalctl to get the logs. By default, NetworkManager logs are not verbose and thus not very helpful for investigating a problem in detail. You can change the logging level at runtime with nmcli general logging level TRACE domains ALL. But usually a better way is to collect full logs from the start, by configuring level=TRACE in NetworkManager.conf. See NetworkManager.conf(5) manual. Note that trace logs of NetworkManager are verbose and systemd-journald might rate limit some lines. Possibly disable rate limiting first with the RateLimitIntervalSec and RateLimitBurst options of journald (see journald.conf(5) manual).

NetworkManager does not log any secrets. However, you are advised to check whether anything private sensitive gets logged before posting. When reporting an issue, provide complete logs and avoid modifications (for privacy) that distort the meaning.

## /VAR/LIB/NETWORKMANAGER/SECRET_KEY AND /ETC/MACHINE-ID
The identity of a machine is important as various settings depend on it. For example, ipv6.addr-gen-mode=stable and ethernet.cloned-mac-address=stable generate identifiers by hashing the machine's identity. See also the connection.stable-id connection property which is a per-profile seed that gets hashed with the machine identity for generating such addresses and identifiers.

If you backup and restore a machine, the identity of the machine probably should be preserved. In that case, preserve the files /var/lib/NetworkManager/secret_key and /etc/machine-id. On the other hand, if you clone a virtual machine, you probably want that the clone has a different identity. There is already existing tooling on Linux for handling /etc/machine-id (see machine-id(5)).

The identity of the machine is determined by the /var/lib/NetworkManager/secret_key. If such a file does not exist, NetworkManager will create a file with random content. To generate a new identity just delete the file and after restart a new file will be created. The file should be read-only to root and contain at least 16 bytes that will be used to seed the various places where a stable identifier is used.

Since 1.16.0, NetworkManager supports a version 2 of secret-keys. For such keys /var/lib/NetworkManager/secret_key starts with ASCII "nm-v2:" followed by at least 32 bytes of random data. Also, recent versions of NetworkManager always create such kinds of secret-keys, when the file does not yet exist. With version 2 of the secret-key, /etc/machine-id is also hashed as part of the generation for addresses and identifiers. The advantage is that you can keep /var/lib/NetworkManager/secret_key stable, and only regenerate /etc/machine-id when cloning a VM.

## BUGS
Please report any bugs you find in NetworkManager at the NetworkManager issue tracker[1].

## SEE ALSO
NetworkManager home page[2], NetworkManager.conf(5), NetworkManager-dispatcher(8), NetworkManager-wait-online.service(8), nmcli(1), nmcli-examples(7), nm-online(1), nm-settings-nmcli(5), nm-applet(1), nm-connection-editor(1), udev(7)

## NOTES
1.

NetworkManager issue tracker

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues

2.

NetworkManager home page

https://networkmanager.dev