multipathd

title: multipathd(8)

summary: Multipath daemon.

text:
# multipathd(8)

## NAME
multipathd - Multipath daemon.

## SYNOPSIS
multipathd [-d] [-s] [-v verbosity] [-B] [-w]

multipathd [-v verbosity] -kcommand

multipathd [-v verbosity] -k

## DESCRIPTION
The multipathd daemon is in charge of checking for failed paths. When this happens, it will reconfigure the multipath map the path belongs to, so that this map regains its maximum performance and redundancy.

With the -k option, multipathd acts as a client utility that sends commands to a running instance of the multipathd daemon (see COMMANDS below).

In this Linux distribution, multipathd does not run unless a /etc/multipath.conf file exists.

## OPTIONS
-d

Foreground Mode. Don't daemonize, and print all messages to stdout and stderr.

-s

Suppress timestamps. Do not prefix logging messages with a timestamp.

-v level

Verbosity level. Print additional information while running multipathd. A level of 0 means only print errors. A level of 3 or greater prints debugging information as well.

-B

Read-only bindings file. multipathd will not write to the user_friendly_names bindings file. If a user_friendly_name doesn't already exist for a device, it will use its WWID as its alias.

-kcommand

multipathd executes the given command (see COMMANDS below). If the command contains whitespace or shell special characters, it needs to be quoted like in multipathd -k'show topology'. No whitespace is allowed between the -k and the command string. Commands can also be issued without using -k. In this case, the command string should not be quoted. Command arguments that contain whitespace or special characters still need to be quoted, like in multipathd show paths format "%n %w"

-k

multipathd executes the multipathc interactive shell for entering commands (see COMMANDS below).

-n

IGNORED. Use the option find_multipaths to control the treatment of newly detected devices by multipathd. See multipath.conf(5).

-w

Since kernel 4.14 a new device-mapper event polling interface is used for updating multipath devices on dmevents. Use this flag to force it to use the old event waiting method, based on creating a separate thread for each device.

## COMMUNICATING WITH MULTIPATHD
In addition to the multipathd CLI, the libmpathcmd library can be used to send commands (see COMMANDS below) to the multipathd daemon from other programs. By default, multipathd listens on both the @/org/kernel/linux/storage/multipathd abstract namespace socket and the /run/multipathd.socket socket file. libmpathcmd will use either of these sockets to connect to multipathd. The socket file can be useful to communicate with multipathd from different namespaces since it can be bind mounted in them, unlike the abstract namespace socket. Multipathd will accept list|show commands from any user. All other commands must be issued by root.

It is possible to change the sockets that multipathd listens on. If multipathd.socket is running, multipathd will use the sockets it listens on. A maximum of two sockets can be defined by multipathd.socket, and by default it listens on @/org/kernel/linux/storage/multipathd and /run/multipathd.socket. If multipathd.socket is not running, a single socket can be configured for listening on by setting the MULTIPATH_SOCKET_NAME environment variable when starting multipathd. This environment variable must also be set to make multipathd CLI commands (or any other program using libmpathcmd) connect to the multipathd daemon using a non-default socket, regardless of whether that socket was set for the daemon using multipathd.socket or the MULTIPATH_SOCKET_NAME environment variable.

## COMMANDS
The following commands can be used in interactive mode:

list|show paths

Show the paths that multipathd is monitoring, and their state.

list|show paths [raw] format $format

Show the paths that multipathd is monitoring, using a format string with path format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Path format wildcards" below.

list|show path $path

Show whether path $path is offline or running.

list|show maps|multipaths

Show the multipath devices that the multipathd is monitoring.

list|show maps|multipaths [raw] format $format

Show the status of all multipath devices that the multipathd is monitoring, using a format string with multipath format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Multipath format wildcards" below.

list|show maps|multipaths status

Show the status of all multipath devices that the multipathd is monitoring.

list|show maps|multipaths stats

Show some statistics of all multipath devices that the multipathd is monitoring.

list|show maps|multipaths topology

Show the current multipath topology. Same as 'multipath -ll'.

list|show maps|multipaths json

Show information about all multipath devices in JSON format.

list|show topology

Show the current multipath topology. Same as 'multipath -ll'.

list|show map|multipath $map topology

Show topology of a single multipath device specified by $map, for example 36005076303ffc56200000000000010aa. This map could be obtained from 'list maps'.

list|show map|multipath $map [raw] format $format.

Show the status of multipath device $map, using a format string with multipath format wildcards. Adding raw will remove the headers and alignment padding from the output. See "Multipath format wildcards" below.

list|show map|multipath $map json

Show information about multipath device $map in JSON format.

list|show wildcards

Show the format wildcards used in interactive commands taking $format. See "Format Wildcards" below.

list|show config

Show the currently used configuration, derived from default values and values specified within the configuration file /etc/multipath.conf.

list|show config local

Show the currently used configuration like show config, but limiting the devices section to those devices that are actually present in the system.

list|show blacklist

Show the currently used blacklist rules, derived from default values and values specified within the configuration file /etc/multipath.conf.

list|show devices

Show all available block devices by name including the information if they are blacklisted or not.

list|show status

Show the number of path checkers in each possible state, the number of monitored paths, and whether multipathd is currently handling a uevent.

list|show daemon

Show the current state of the multipathd daemon.

reset maps|multipaths stats

Reset the statistics of all multipath devices.

reset map|multipath $map stats

Reset the statistics of multipath device $map.

add path $path

Add a path to the list of monitored paths. $path is as listed in /sys/block (e.g. sda).

remove|del path $path

Stop monitoring a path. $path is as listed in /sys/block (e.g. sda).

add map|multipath $map

Add a multipath device to the list of monitored devices. $map can either be a device-mapper device as listed in /sys/block (e.g. dm-0) or it can be the alias for the multipath device (e.g. mpath1) or the uid of the multipath device (e.g. 36005076303ffc56200000000000010aa).

remove|del maps|multipaths

Remove all multipath devices.

remove|del map|multipath $map

Remove the multipath device $map.

resize map|multipath $map

Resizes map $map to the given size.

switch|switchgroup map|multipath $map group $group

Force a multipath device to switch to a specific path group. $group is the path group index, starting with 1.

reconfigure

Rereads the configuration, and reloads all changed multipath devices. This also happens at startup, when the service is reload, or when a SIGHUP is received.

reconfigure all

Rereads the configuration, and reloads all multipath devices regardless of whether or not they have changed. This also happens when multipath -r is run.

suspend map|multipath $map

Sets map $map into suspend state.

resume map|multipath $map

Resumes map $map from suspend state.

reset map|multipath $map

Reassign existing device-mapper table(s) use the multipath device, instead of its path devices.

reload map|multipath $map

Reload a multipath device.

fail path $path

Sets path $path into failed state.

reinstate path $path

Resumes path $path from failed state.

disablequeueing maps|multipaths

Disable queueing on all multipath devices.

restorequeueing maps|multipaths

Restore queueing to the configured no_path_retry setting on all multipath devices whose queueing has been previously disabled by the disablequeueing command. Note: If no_path_path_retry is set to queue for a limited number of retries after all paths have failed, this will not enable queueing if there are no active paths.

disablequeueing map|multipath $map

Disable queuing on multipathed map $map.

restorequeueing map|multipath $map

restore queueing to the configured no_path_retry setting on multipathed map $map whose queueing has been previously disabled by the disablequeueing command. Note: If no_path_path_retry is set to queue for a limited number of retries after all paths have failed, this will not enable queueing if there are no active paths.

forcequeueing daemon

Forces multipathd into queue_without_daemon mode, so that no_path_retry queueing will not be disabled when the daemon stops.

restorequeueing daemon

Restores configured queue_without_daemon mode.

setprstatus map|multipath $map

Enable persistent reservation management on $map.

setprstatus map|multipath $map pathlist $pathlist

Enable persistent reservation management on $map, and notify multipathd of the paths that have been registered, so it doesn't attempt to re-register them.

unsetprstatus map|multipath $map

Disable persistent reservation management on $map.

getprstatus map|multipath $map

Get the current persistent reservation management status of $map.

getprkey map|multipath $map

Get the current persistent reservation key associated with $map.

setprkey map|multipath $map key $key

Set the persistent reservation key associated with $map to $key in the prkeys_file. This key will only be used by multipathd if reservation_key is set to file in /etc/multipath.conf.

unsetprkey map|multipath $map

Remove the persistent reservation key associated with $map from the prkeys_file. This will only unset the key used by multipathd if reservation_key is set to file in /etc/multipath.conf.

setmarginal path $path

move $path to a marginal pathgroup. The path will remain in the marginal path group until unsetmarginal is called. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

unsetmarginal path $path

return marginal path $path to its normal pathgroup. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

unsetmarginal map $map

return all marginal paths in $map to their normal pathgroups. This command will only work if marginal_pathgroups is enabled and there is no Shaky paths detection method configured (see the multipath.conf man page for details).

quit|exit

End interactive session.

shutdown

Stop multipathd.

## Format Wildcards
Multipathd commands that take a $format option require a format string. This string controls how a device is printed and should include format wildcards. When the devices are printed, these wildcards will be replaced by the appropriate device information. The following wildcards are supported.

Multipath format wildcards

%n

The device name.

%w

The device WWID (uuid).

%d

The device sysfs name (dm-<minor_nr>).

%F

The device failback setting. For deferred failbacks, it will either include the configured time if a deferred failback is not in progress, or it will show the current progress of a deferred failback in seconds.

%Q

The device no_path_retry setting. If no_path_retry is set to a number of retries, it will either print the configured number of checker retries if the device is not in recovery mode, the number of seconds until queueing is disabled if the device is queueing in recovery mode, or off if the device has disabled queueing.

%N

The number of active paths for the device.

%r

The device write-protect setting, either ro or rw.

%t

The state of the device in device-mapper. suspend if the devices is suspended, and active otherwise.

%S

The device size, using the suffixes K, M, G, T, and P, to stand for kilobytes, megabytes, gigabytes, terabytes, and petabytes, respectively.

%f

The "features" string of the device-mapper table in the kernel.

%x

The number of times the device has entered a state where it will fail IO. This is an alias for the %4 wildcard. This value can be reset with the 'reset map $map stats' command.

%h

The device table hardware handler string.

%A

The last action multipathd took on the device. This wildcard is for debugging use, as understanding its meaning requires looking at the code.

%0

The number of times a path in the device has failed. This value can be reset with the 'reset map $map stats' command.

%1

The number of times multipathd has initiated a pathgroup switch for the device. This value can be reset with the 'reset map $map stats' command.

%2

The number of times multipathd has loaded a new table for the device. This value can be reset with the 'reset map $map stats' command.

%3

The approximate number of seconds that multipathd has spent queueing with no usable paths. This value can be reset with the 'reset map $map stats' command.

%4

The number of times the device has entered a state where it will fail IO. This is an alias for the %x wildcard. This value can be reset with the 'reset map $map stats' command.

%s

The vendor/product string for the device.

%v

The array vendor string for the device.

%p

The array product string for the device.

%e

The array firmware revision string for the device.

%G

The foreign library used for the device, or -- for native device-mapper multipath devices. See "FOREIGN MULTIPATH SUPPORT" in /etc/multipath.conf(5).

%g

Data from vendor specific vpd pages for the device, if any. Currently multipathd supports VPD page 0xc0 for HPE 3PAR / Primera / Alletra storage arrays.

%k

The actual max_sectors_kb setting for the device (which may be different from the configured one).

Path format wildcards

%w

The device WWID (uuid).

%i

The device Host:Channel:Id:Lun for SCSI devices. The device "Controller Instance Number":"Controller ID":"Namespace Instance Number":"Namespace ID" for NVMe devices. The Controller and Namespace Instance Numbers match the NVMe device name: "nvme<Controller_Instance_Number>n<Namespace_Instance_Number>"

%d

The device sysfs name.

%D

The device major:minor

%t

The device-mapper state of the device, either active or failed.

%o

The offline state of the device. This shows "offline" if the device's "state" attribute in sysfs is "offline" (for SCSI) or "dead" (for NVMe). For all other sysfs states, it shows "running".

%T

The multipathd path checker state of the device. The possible states are:

ready

The device is ready to handle IO.

faulty

The device is unusable.

shaky

The device is not able to handle IO but can still be accessed to check the priority.

ghost

The device is in stand-by state.

i/o pending

The checker is in the process of determining the device state.

i/o timeout

The path checker has timed out, failing the device.

delayed

The device appears usable, but it being delayed for marginal path checking.

undef

The device either is not part of a multipath device, or its path checker has not yet run.

%s

The vendor/product/revision string for the device.

%c

The name of the device's path checking algorithm

%C

The progress towards the next path checker run on the device in seconds.

%p

The device priority.

%S

The device size, using the suffixes K, M, G, T, and P, to stand for kilobytes, megabytes, gigabytes, terabytes, and petabytes, respectively.

%z

The device serial number.

%M

The device marginal state, either marginal or normal.

%m

The multipath device that this device is a path of, or [offline] if this device could not be added to a device because it is offline or [orphan] if it is not part of any multipath device.

%N

The host World Wide Node Name (WWNN) of the device, if any.

%n

The target World Wide Node Name (WWNN) of the device, if any.

%R

The host World Wide Port Name (WWPN) of the device, if any.

%r

The target World Wide Port Name (WWPN) of the device, if any.

%a

The host adapter name for the device (only SCSI devices).

%G

The foreign library used for the device, or -- for native device-mapper multipath devices. See "FOREIGN MULTIPATH SUPPORT" in /etc/multipath.conf(5).

%g

Data from vendor specific vpd pages for the device, if any. Currently multipathd supports VPD page 0xc0 for HPE 3PAR / Primera / Alletra storage arrays.

%0

The number of times this device has failed.

%P

The device protocol. See /etc/multipath.conf(5).

%I

The device initialization state. Devices that have been fully initialized are shown as ok.

%L

The device SCSI LUN ID in hexadecimal format. This is only meaningful for SCSI devices.

%A

The ALUA Target Port Group ID for the device, if applicable.

%k

The actual max_sectors_kb setting for the device (which may be different than the configured one).

## SYSTEMD INTEGRATION
When compiled with systemd support two systemd service files are installed, multipathd.service and multipathd.socket. If enabled, the multipathd.socket service instructs systemd to intercept the CLI command socket, so that any call to the CLI interface will start-up the daemon if required. The multipathd.service file carries the definitions for controlling the multipath daemon. The daemon itself uses the sd_notify(3) interface to communicate with systemd. The following unit keywords are recognized:

WatchdogSec=

Enables the internal watchdog from systemd. multipath will send a notification via sd_notify(3) to systemd to reset the watchdog. If specified the polling_interval and max_polling_interval settings will be overridden by the watchdog settings. Please note that systemd prior to version 207 has issues which prevent the systemd-provided watchdog from working correctly. So the watchdog is not enabled per default, but has to be enabled manually by updating the multipathd.service file.

OOMScoreAdjust=

Overrides the internal OOM adjust mechanism.

LimitNOFILE=

Overrides the max_fds configuration setting.

## SEE ALSO
multipathc(8), multipath(8), kpartx(8)

sd_notify(3), systemd.service(5).

## AUTHORS
multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others.


munged

package: munge

title: munged(8)

summary: MUNGE daemon

text:
# munged(8)

## NAME
munged - MUNGE daemon

## SYNOPSIS
munged [OPTION]...

## DESCRIPTION
The munged daemon is responsible for authenticating local MUNGE clients and servicing their credential encode & decode requests.

All munged daemons within a security realm share a common key. All hosts within this realm are expected to have common users/UIDs and groups/GIDs. The key is used to cryptographically protect the credentials; it is created with the mungekey command.

When a credential is created, munged embeds metadata within it including the effective UID and GID of the requesting client (as determined by munged) and the current time (as determined by the local clock). It then compresses the data, computes a message authentication code, encrypts the data, and base64-encodes the result before returning the credential to the client.

When a credential is validated, munged first checks the message authentication code to ensure the credential has not been subsequently altered. Next, it checks the embedded UID/GID restrictions to determine whether the requesting client is allowed to decode it. Then, it checks the embedded encode time against the current time; if this difference exceeds the embedded time-to-live, the credential has expired. Finally, it checks whether this credential has been previously decoded on this host; if so, the credential has been replayed. If all checks pass, the credential metadata and payload are returned to the client.

## OPTIONS
-h, --help

Display a summary of the command-line options.

-L, --license

Display license information.

-V, --version

Display version information.

-f, --force

Force the daemon to run if at all possible. This overrides warnings for an existing local domain socket, a lack of entropy for the PRNG, and insecure file/directory permissions. Use with caution as overriding these warnings can affect security.

-F, --foreground

Run the daemon in the foreground.

-M, --mlockall

Lock pages into memory to prevent the daemon from being swapped to disk. This can prevent authentication delays under extreme memory pressure. Requires sufficient memory lock limits. See the MEMORY LOCKING section below.

-s, --stop

Stop the daemon bound to the socket and wait for it to shut down. Use with the --socket option to target a daemon bound to a non-default socket location. This option exits with a zero status if the specified daemon was successfully stopped, or a non-zero status otherwise.

-S, --socket path

Specify the local domain socket for communicating with clients.

-v, --verbose

Be verbose.

--auth-server-dir directory

Specify an alternate directory in which the daemon will create the pipe used to authenticate clients. The recommended permissions for this directory are 0711. This option is only valid on platforms where client authentication is performed via a file-descriptor passing mechanism.

--auth-client-dir directory

Specify an alternate directory in which clients will create the file used to authenticate themselves to the daemon. The recommended permissions for this directory are 1733. This option is only valid on platforms where client authentication is performed via a file-descriptor passing mechanism.

--benchmark

Disable recurring timers in order to reduce some noise while benchmarking. This affects the PRNG entropy pool, supplementary group mapping, and credential replay hash. Do not enable this option when running in production.

--group-check-mtime boolean

Specify whether the modification time of /etc/group should be checked before updating the supplementary group membership mapping. If this value is non-zero, the check will be enabled and the mapping will not be updated unless the file has been modified since the last update.

--group-update-time seconds

Specify the number of seconds between updates to the supplementary group membership mapping; this mapping is used when restricting credentials by GID. A value of 0 causes it to be computed initially but never updated (unless triggered by a SIGHUP). A value of -1 causes it to be disabled.

--key-file path

Specify an alternate pathname to the key file.

--listen-backlog integer

Specify the socket's listen backlog limit; note that the kernel may impose a lower limit. A value of 0 uses the software default. A value of -1 specifies SOMAXCONN, the maximum listen backlog queue length defined in <sys/socket.h>.

--log-file path

Specify an alternate pathname to the log file.

--max-ttl integer

Specify the maximum time-to-live (in seconds) for credentials. This value caps the TTL during both encoding and decoding. The hard-coded upper bound is 3600 seconds (1 hour); the default is 3600. Reducing this value will limit the maximum retention time for replay cache entries, which is viable if clocks within the MUNGE realm can be kept in sync with minimal skew.

--num-threads integer

Specify the number of threads to spawn for processing credential requests.

--origin address

Specify the origin address that will be encoded into credential metadata. This can be a hostname or IPv4 address; it can also be the name of a local network interface, in which case the first IPv4 address found assigned to that interface will be used. The default value is the IPv4 address of the hostname returned by gethostname(). Failure to resolve the address will result in an error; if overridden, the origin will be set to the null address.

--pid-file path

Specify an alternate pathname for storing the Process ID of the daemon.

--seed-file path

Specify an alternate pathname to the PRNG seed file.

--syslog

Redirect log messages to syslog when the daemon is running in the background.

--trusted-group group

Specify the group name or GID of the "trusted group". This is used for permission checks on a directory hierarchy. Directories with group write permissions are allowed if they are owned by the trusted group (or the sticky bit is set).

## MEMORY LOCKING
The --mlockall option locks pages into memory to prevent swapping under memory pressure.

Memory usage scales with the number of worker threads, size of the user and group databases (when supplementary group mapping is enabled), and the rate of credential decoding (which grows the replay cache).

Many systems default to an insufficient memory lock limit. A minimum of 16 MB is required for basic operation; 64-256 MB is recommended for typical configurations. Increase it in one of the following ways:

### systemd-based systems
Create /etc/systemd/system/munge.service.d/memlock.conf:

```
[Service]
LimitMEMLOCK=256M
```

Then reload and restart:

```
systemctl daemon-reload
systemctl restart munge.service
```

### PAM limits
Add to /etc/security/limits.conf (values in KB):

```
munge  soft  memlock  262144
munge  hard  memlock  262144
```

On systemd-based systems, PAM limits are ignored for services. Use the systemd configuration instead.

### Shell environment (for testing)
Set the limit before starting munged (value in KB):

```
ulimit -l 262144
munged --mlockall
```

### Security Considerations
The replay cache is unbounded and grows with credential decode rate. Replay entries are retained until credentials expire based on their time-to-live (TTL). Credentials have a default TTL of 5 minutes; clients can specify up to the maximum TTL configured on the encoding munged (1 hour by default, configurable via --max-ttl). During decoding, the credential's TTL is capped at the decoding munged's maximum TTL. When --mlockall is specified, replay entries are locked in physical memory.

On systems with untrusted local users, an attacker could encode credentials with the maximum TTL (1 hour by default) and decode them repeatedly to fill the replay cache. Once the memory lock limit is reached, munged will likely terminate when attempting to allocate additional memory, causing a denial of service.

Use this option only on trusted systems where local users are controlled, or set the memory lock limit to a reasonable upper bound rather than unlimited. Monitor munged's locked memory usage on high-volume systems to ensure the limit is not approached during normal operation. Reducing --max-ttl can limit replay cache growth but requires tight clock synchronization.

## SIGNALS
SIGHUP

Immediately update the supplementary group membership mapping instead of waiting for the next scheduled update; this mapping is used when restricting credentials by GID.

SIGTERM

Terminate the daemon.

## NOTES
All clocks within a security realm must be kept in sync within the credential time-to-live setting.

While munged prevents a given credential from being decoded on a particular host more than once, nothing prevents a credential from being decoded on multiple hosts within the security realm before it expires.

## AUTHOR
Chris Dunlap <cdunlap@llnl.gov>

## COPYRIGHT
Copyright (C) 2007-2025 Lawrence Livermore National Security, LLC.

Copyright (C) 2002-2007 The Regents of the University of California.

MUNGE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Additionally for the MUNGE library (libmunge), you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

## SEE ALSO
munge(1), remunge(1), unmunge(1), munge(3), munge_ctx(3), munge_enum(3), munge(7), mungekey(8).

https://github.com/dun/munge

branch: sisyphus


mungekey

title: mungekey(8)

summary: MUNGE key management utility

text:
# mungekey(8)

## NAME
mungekey - MUNGE key management utility

## SYNOPSIS
mungekey [-c] [-b bits] [-f] [-k keyfile] [-v]

## DESCRIPTION
The mungekey executable is the key management utility for MUNGE. It should be run by the same user that starts the munged daemon.

If no options are specified, mungekey will attempt to create a new key using the default settings; this will fail if the keyfile already exists.

All munged daemons within a security realm must use the same key. In other words, all hosts within an administrative group (or cluster) using MUNGE for authentication must use the same key; this keyfile can be created on one host and then securely copied to all other hosts.

## OPTIONS
-b, --bits integer

Specify the number of bits in the key being created [256-8192].

-c, --create

Create a new keyfile.

-f, --force

Force the keyfile to be overwritten if it already exists.

-h, --help

Display a summary of the command-line options.

-k, --keyfile path

Specify the keyfile pathname.

-L, --license

Display license information.

-v, --verbose

Be verbose.

-V, --version

Display version information.

## FILES
/etc/munge/munge.key

Contains the shared cryptographic key for hosts within the security realm.

## AUTHOR
Chris Dunlap <cdunlap@llnl.gov>

## COPYRIGHT
Copyright (C) 2007-2025 Lawrence Livermore National Security, LLC.

Copyright (C) 2002-2007 The Regents of the University of California.

MUNGE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Additionally for the MUNGE library (libmunge), you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

## SEE ALSO
munge(1), remunge(1), unmunge(1), munge(3), munge_ctx(3), munge_enum(3), munge(7), munged(8).

https://github.com/dun/munge


mxk

package: mxk

title: mxk(8)

summary: configurable input rewriting server

text:
# mxk(8)

## NAME
mxk - configurable input rewriting server

## SYNOPSIS
mxk [-a] [-d] [-c] [-h] [-q] [-v] [-z] [-u [unix-socket]] [-p script-file] [-C [log-file]] [-D [log-file]]

## OPTIONS
-a

Reattach to a running mxk instance

-c

Display copyright information and copying conditions

-d

Run as daemon, detach into background once the interpreter finishes

-h

Help summary

-q

Run quietly

-v

Increase verbosity. Can be given multiple times

-z

Disable interactive interpreter

-p file

Load commands into interpreter from file

-u socket

Provide a control interface on the specified unix socket. Leave out socket to disable the control interface

-C file

Record debug information leading up to a crash to the specified file

-D file

Write debug log to the specified file, provided debugging has been enabled during the compile

## WARNINGS
keyboards

are not all created equal. Inferior ones are unable to report complex chords

mxk

is currently poorly tested and badly documented

mxk

can be configured to grab your keyboard, rendering your system inoperable until mxk is killed or the system rebooted

mxk

operates on input devices which may process confidential information such as passwords

## DESCRIPTION
mxk (Marc's eXtended Keyboard) rewrites input events. It receives input events from the linux kernel, rewrites them and sends them back to the kernel via a virtual input device.

mxk uses evdev to receive input events and uinput to queue them back for processing by the kernel. Thus the uinput and evdev modules have to be loaded or compiled into the kernel. It also means that the corresponding device files have to exist (see the FILES section).

Between evdev and uinput, the mxk process can perform a number of transformations. The transformation are specified using a set of commands. The commands can be issued in one of the following ways

☞

Interactively at startup: Unless the -z option has been used, mxk will run its interpreter on the terminal on which it was started.

☞

From a script file: A script file is given with the -p option. Usually mxk script files are installed in the /etc/mxk directory.

☞

By connecting to a running instance: When invoked mxk with the -a option mxk will connect to an already running instance where further commands can be entered, provided the control socket has not been disabled.

Note that in all cases the mxk command interpreter does not display a prompt.

## Examples
The below line will start mxk without running an interpreter on the current tty (-z) , will have mxk detach from the current terminal (-d run as a daemon) and interpret a script (-p /etc/mxk/example.mxk) :

~# mxk -dzp /etc/mxk/example.mxk

The next example shows an interactive session. Output is shown in bold while commands are italicised :

~# mxk

console: ready

list-sources

/dev/input/event0: unused: ImExPS/2 Generic Explorer Mouse

/dev/input/event1: unused: PC Speaker

/dev/input/event2: unused: AT Translated Set 2 keyboard

3 entries

halt

console: normal server exit

## Command Overview
mxk commands are used to construct a processing graph (a structure of nodes and edges). Data arrives at source nodes, is processed at different intermediate nodes and is sent back to kernel at the target node.

In other words, mxk uses a data flow architecture which, unlike a shell pipeline, can have arbitrary branches. This feature can cause problems if used incorrectly as mxk does not guard against loops. A graph containing a loop can generate a continuous stream of events - this is almost always undesirable.

Also unlike a shell (where the entire pipeline is constructed in one command), mxk uses separate commands to create and configure individual nodes. Once created, the nodes are then connected using another command. These connections between nodes (edges) are anonymous and unidirectional, as in the case in a shell pipeline.

Each node belongs to a node type. Each node type implements a certain function, for example source nodes collect data from evdev, while nodes of the stats type maintain event statistics. If the mxk processing graph is compared to a shell pipeline, a node type can be thought of as a particular utility, while a node is equivalent to a process instance of that utility.

The list-nodes command can be used to view all available node types. Generally commands implemented by a particular node type end in the name of the type. For example, the command start-vector applies to the vector node type.

To construct a graph, nodes (instances of a type) need to be created, configured and then connected to each other. Most nodes are created using a start-* command and then configured using type specific commands.

Nodes are connected to each other using the connect-node command. This command can be thought of as being the equivalent to the pipe token when thinking of a mxk processing graph in terms of a shell pipeline.

Nodes of the same type can be numbered for identification. Generally the first parameter to a command contains the node id. The id is local to a node type. To generate an anonymous node or to refer to all nodes of a particular type, use the id 0.

Note that the manual page is currently incomplete (it only describes some node types) please consult the example scripts in /etc/mxk and the source where there are gaps.

## General Commands
help will list all available commands.

echo will display the given parameters.

copying will display the copyright notice.

version will display the version number.

quit will disconnect from a running mxk instance. If the -d option has been given when starting mxk , the server process will detach from the terminal and continue running as a daemon.

halt will stop a running mxk instance. This command should be used to stop mxk rather than quit or control-C , as the latter may leave a running mxk server instance.

## Node Management
connect-node will connect the output of the node given as its first parameter to the input of the node given as its second parameter.

Nodes can be specified as a node type name, optionally followed a colon and a node identifier.

The output of one node may be used as input to several nodes, similarly a node may receive input from the output of several nodes.

The below command will connect all input source nodes to array node with identifier 2:

connect-node source array:2

list-nodes displays the node types which are available. Individual nodes of particular type need to be created first before they can be used by the connect-node command. Node instances are created, displayed and manipulated using type specific commands.

## Source nodes
The input devices from which mxk can generate input nodes can be displayed using the list-sources command.

Source nodes are created using the file-source, name-source, or caps-source commands. The first parameter to these commands is the node number.

The second parameter to file-source specifies the event device file. A device file should not be opened multiple times. The following example will open the first evdev source and map it to identifier one:

file-source 1 /dev/input/event0

name-source opens an unused input device which has a given name. The second parameter is used as a substring to be matched against the input device name. The match is case sensitive and exact. The following example will open the first device which contains the lowercase string joystick in its name:

name-source 2 joystick

caps-source opens an unused input source which emits a particular set of event types, such as relative motion or key press events. Event types are given as second and further parameters. Event types prefixed with a bang (exclamation mark) indicate capabilities which the device can not have. The following command will open the first device which provides absolute but not relative motion commands:

caps-source 3 key !relative absolute

used-sources lists the input devices which have been opened and their state.

fixup-source source will remap an autorepeat key event to a release and press event, as autorepeat events are discarded by most processing nodes. This is the default state.

repeat-source will disable the translation of autorepeat events and relay them unchanged to downstream processing nodes.

norepeat-source will discard autorepeat key events entirely. This may be needed where a downstream node inserts its own autorepeats.

lock-source activates an opened source for exclusive use. An exclusively used source is inaccessible to other parts of the system. Hence this command should only be issued carefully and only once the processing graph has been set up completely. It is this command which, if used incorrectly, will block input and lock you out of your system.

activate-source activates an opened source in nonexclusive mode. This means that input events reach both mxk and the rest of the system. If used incorrectly this will result in duplicated events.

bypass-source will discard events from an opened source. A newly opened source will always start in bypass mode. Generally a source node should be activated or locked once the rest of the processing graph has been initialised, otherwise no input is collected.

## Statistics node
Key press statistics collection nodes are created with the start-stat command. The first parameter to this command is the node id.

The statistics collected sofar can be displayed with the list-stats command.

The following command sequence collects statistics from the first input device:

file-source 0 /dev/input/event0

start-stat 0

connect-node source:0 stat:0

activate-source 0

list-stat 0

Note the use of activate-source rather than lock-source, if the latter is used, events from this device would not reach any other application. Issue further list-stat commands interactively to see the statistics at a later stage.

## Target node
A target node is created with the start-target command. This command requires that the uinput device file exists.

A target device is visible in the output of the list-sources command but should not be used as a source. Actually mxk will refuse to use it as a source.

Generally only one instance of the target node needs to be created.

By default, start-target creates a virtual device which is declared to only report keypress, but of all keys.

To change this, specify additional parameters. The first parameter is the node id, subsequent parameters allow users to add relative or absolute motion capabilities to the target, or to select particular keys only.

The example:

start-target 0 key:leftbutton relative:x relative:y

will declare a target which can report relative motion along the x and y-axes in addition to a single keypresses, in other words a one button mouse.

## Generic Brailler Node
The generic brailler node can be use to implement chording.

start-genb creates a genb instance. The first parameter is the identifier, the identifier is followed by one to eight key events which should be used to construct the chord. The example :

start-genb 0 s d f

will generate seven key combinations from a chord containing some combination of s d or f. The output keys are virtual keys (virt1 to virt7) which can be remapped using the array node. Up to eight keys can be used to construct a chord, yielding a maximum of 255 virtual key outputs.

Note that output keypress is only generated when a key in the chord is released. The output keyrelease is generated when all input keys are released. When a repeater module is appended to a genb module, it is possible to generate autorepeats by pressing a chord and releasing only one of the input chord keys.

list-genb lists created generic brailler node instances.

An alternative to the genb node is the chord node.

## Autorepeat Node
An autorepeat node will transform a key single long keypress into several shorter ones.

start-repeater creates an autorepeat node. Its first parameter is the node id, the second the delay and the third the rate. Delay and rate are given in integer milliseconds.

list-repeater will list existing repeater nodes.

adjust-repeater makes it possible to adjust the repeat rate on the fly. The first parameter specifies the repeater node id, the second the adjustment value, the third and fourth set the keys to increase or decrease the autorepeat rate.

Note that some input devices generate their own autorepeat events for certain keys, these may have to be filtered using the norepeat-source command when a repeater node is used. Also note that the operating system scheduler may not always run mxk when desired, making autorepeats jerky under load. Run mxk at higher priority to reduce this problem.

## Array Node
An array node maps a single keypress or release to one or more other events. An array is created using the start-array command, where the first parameter is the node id.

press-array is used to map a keypress to a sequence of events. The first parameter to press-array is the array id, the second parameter the keypress to match. Subsequent parameters are the events to generate on a match.

release-array implements the same function as press-array but matches key releases.

The following example will map the capslock key to the escape key. It will also move the mouse pointer down by ten:

start-array 0

press-array 0 capslock escape/press sync: relative:y/10 sync:

release-array 0 capslock escape/release sync:

ignore-array will configure the node not to forward incoming events which did not match any entry created with the press-array or release-array commands.

bypass-array is the inverse of ignore-array , it configures the node to simply relay events which did not match any entry.

## Sorter Node
A sorter node makes it possible to group input events into different groups (bins). Each bin can serve as input to a different set of nodes, making it possible to direct different events through different parts of the processing graph.

A sorter node is started using the start-sorter command. The first parameter is the identifier of the sorter, the next is the currently active bin.

The active bin is used by the node-connect command. The command connects the active bin as output to the input of the node given as its second parameter.

To change the active bin use the bin-sorter command. The first parameter is the identifier of the sorter, the second is the bin number which is to be made active.

To assign a particular key to a bin use the match-sorter command. The first parameter is the identifier of the sorter, the second parameter is the key to be matched, and the last is the bin to which the key is to be assigned.

list-sorters will display the existing sorter nodes.

## Timer Node
A timer node will emit a single keypress event once a timer expires. This event can be used by downstream nodes to generate more complex activity.

A timer node can optionally examine its input events for one of three user defined keypress events. These events arm, reset or clear the timer respectively. A reset restarts the timer, while an arm will not affect an already running timer, only start an inactive one.

start-timer will create a timer instance. The first parameter is its identifier, the second its period in milliseconds, the third the keypress event to emit when the timer expires.

trigger-timer sets the input key event which starts the timer. The first parameter is the timer id, the second is the key to match. A running timer is not reset.

reset-timer will start the timer, regardless of it running or not. The parameters are the same as for trigger-timer

clear-timer will disable a running timer. The parameters are the same as for trigger-timer

arm-timer will start a timer identified by its first parameter.

off-timer will stop a running timer identified by its first parameter.

auto-timer will configure a timer to rearm once it expires. The first parameter contains the identifier of the timer to be reconfigured.

single-timer will configure a timer not to arm once it expires. As in the auto-timer case, the first parameter contains the identifier of the timer to be reconfigured.

list-timer will display all timer instances.

## Branch Node
A branch node switches its input to one of two destinations, depending on its state. The destinations and its corresponding states are referred to as up and down. The current state of the branch node can be controlled by events on the input stream.

start-branch will create a branch instance. Its first parameter is its identifier.

key-branch associates a particular key with a set of actions. The first parameter is the branch identifier, the second the key while subsequent arguments list the actions. The following actions are defined:

pass

The key is forwarded to the current destination

hipass

The key event is forwarded, but only if the branch is up

lopass

The key event is forwarded only if the branch is down

toggle

The key event switches from up to down or vice versa

up

The key event switches the branch to the up destination

down

The key event switches the branch to the down destination

default-branch functions similarly to key-branch except that the key parameter is omitted, as this command determines what actions are to be taken for all key events which have not been set by a call to key-branch.

up-branch sets the destination to be the up branch directly. The first parameter is the node identifier. When set to up in this way, subsequent connect-node can be used to connect destination nodes to receive input from the up branch.

down-branch functions analogously to the up-branch command, but operates on the down branch instead.

list-branches lists all known branch instances.

Note that a branch will only change when no keys are pressed in order to prevent a key press taking a different path through the processing graph than its corresponding release.

## Reduce Node
The reduce node is used to filter out unwanted key events. Optionally the relayed key events can be replaced with another simple key event. For more complex substitutions use the array node.

start-reduce creates a reduce instance. The first parameter is the identifier.

key-reduce loads a set of key events into the reduction map. The first parameter is the identifier, subsequent events list the keys.

relay-reduce configures the node to only relay those key events that have been added using the key-reduce command. This is the default mode of operation.

discard-reduce inverts the function of the reduce node. In other words, it configures the node to discard the key events that have been added using the key reduce command. Instead it relays all the events which have not been listed. Note that this commands needs to be given before the key-reduce command is used. Furthermore, using multiple key-reduce commands while changing from relay-reduce to discard-reduce and vice versa can have unpredictable results.

replace-reduce replaces the key events which do get forwarded with the key event specified as second parameter. The first parameter is the node identifier.

self-reduce undoes the effect of a replace-reduce command, in other words the events are forwarded directly and not replaced.

## Bug Node
The bug node can be used to generate different virtual key events from a single key or button by varying the length for which this key is pressed.

A total time period is divided into two or more equal intervals, numbered from one. The number of intervals as well as the overall time period can be set when a node is created. A keypress duration which ends within a given interval generates a virtual key event of the same number. Thus the shortest duration generates a virtual key event one. The virtual events can be remapped using an array node.

start-bug creates a bug instance. The first parameter is the identifier, the second the key to match. The third parameter specifies a total time in milliseconds while the fourth parameter sets the number of intervals.

list-bugs list previously created bug instances.

## Single Node
A single node maps one axis of motion to one of two keypresses, one when encountering movement in the negative direction, the other for the positive direction.

start-single starts a single node. The first parameter is the node identifier, the second parameter the type of movement (either relative or absolute), while the third and fourth parameters specify the key to be emitted for negative and positive motion respectively.

list-singles list previously created single nodes.

limit-single sets a threshold below which no key events will be emitted. The first parameter to this command is the identifier, the second the threshold. The default threshold is the minimum, namely one.

sustain-single will configure the single node to continue pressing the key until a motion below the threshold is encountered.

quick-single will emit a key release event immediately after its corresponding press event.

time-single will emit a key release after a timeout. The first parameter to this command is the node identifier, the second parameter specifies the timeout in milliseconds. This command will cause a single node to combine several movements events in the same direction, provided that they occur within an interval less than the timeout.

## Chord Node
The chord node matches key combinations.

start-chord will start a chord node instance.

list-chord will list all created chord instances.

new-order-chord will match a sequence of keypresses. The first parameter is the node id, the second parameter sets the key event to emit when the sequence is matched. Parameters three and onwards describe the sequence of keypresses to be matched. Only keypresses which have not been released will be matched. Keypresses have to occur in the order specified.

new-set-chord has the same syntax as new-order-chord but does not require ordering, meaning that the keys specified by parameters three and onward do not have to be pressed in the order that they were given.

old-order-chord functions similarly to new-order-chord but also can match keys which have already been released.

old-set-chord functions similarly to new-set-chord but also can match keys which have already been released.

gap-order-chord functions similarly to new-order-chord but disables repeated matching of a continuously depressed key. This forces the release of a key before a further chord containing the particular key can be matched.

gap-set-chord functions like new-set-chord but with the same restiction as described for gap-order-chord above.

Note that the patterns specified by the old-*-chord commands behave somewhat unusually as they may include older, previously unmatched, keypresses. In future this may change.

## Informational commands
list-events will list the event types which mxk can map to symbolic names.

list-codes will list the key or button events that mxk knows about.

ps will list the tasks that the mxk process is currently performing. Each node instance shows up as a task.

## COPYRIGHT
Copyright (C) 1999, 2004-2009 Marc Welz. This software is licensed under the terms of the GNU General Public License version 3 or newer as published by the Free Software Foundation. This software comes with no warranty, not even for merchantability or fitness for a particular purpose.

## BUGS
Probably lots

## FILES
/dev/input/event?

source of events. At the time of writing event0 is a character device which has a major number 13 and minor number of 64, subsequent devices increment the minor number

/dev/input/uinput

event destination. At the time of writing uinput has a major number of 10 and a minor number of 223. Also note that on some systems uinput exists in /dev/misc

/var/run/mxk

control socket

/etc/mxk

location of mxk scripts

## SEE ALSO
mxk-tutorial(8).


mxk-tutorial

title: mxk-tutorial(8)

text:
# mxk-tutorial(8)

## Overview
This tutorial shows you how to write simple mxk scripts. It assumes that you have managed to install mxk successfully.

## First script
As root run mxk without any arguments. You should see output looking something like

~# mxk

mxk: starting

mxk: starting console

mxk: starting unix monitor on /var/run/mxk

mxk: starting keyboard server

mxk: ready to serve requests

console: ready

The line console: ready is significant. It means that the console is ready to accept commands. Ignore the fact that there is no prompt. Just type in a command and then press enter. A good command would be help. This command should have lots of text scrolling past. Lets ignore that for the time being. Type list-sources instead. You should see output like this

list-sources

/dev/input/event0: unused: PC Speaker

/dev/input/event1: unused: AT Translated Set 2 keyboard

/dev/input/event2: unused: ImExPS/2 Generic Explorer Mouse

3 entries

This listing shows you what input devices the kernel thinks are connected to your system. If the listing is empty or you get an error, you either don't have any input devices or the kernel hasn't been built with evdev support. Remember you need a 2.6 series Linux kernel which knows about evdev. Try loading the evdev module explicitly with modprobe evdev or try creating the device files manually with mknod(1) in case of problems.

In all likelihood you will have some odd input devices such as power buttons and PC speakers. We will ignore these and focus on the important devices such as keyboards and mice. In the example the third device ( /dev/input/event2) is a mouse (ImExPS/2 Generic Explorer Mouse). We can tell mxk to open this device. Use the command file-source 0 /dev/input/event2 to open the device as source 0. If the open succeeds we can use the command used-sources to view more information about the device. You should see something like this:

file-source 0 /dev/input/event2

used-sources

0: ImExPS/2 Generic Explorer Mouse: bypass [sync key relative]

1 entry

The fields in the square parenthesis tell us that this device has keys (actually buttons) and can report relative movements. Good. Note the word bypass, it means the device is opened, but won't generate events just yet. We'll change that right at the end of our script, once we have set up everything else.

Now, once we have a source we want to connect something to it. Lets try a translation array. It matches a single key event and replaces it with an array of other events. First create the array, with identifier 0, using the command start-array 0. Then tell the array that for each middle click (middlebutton) we want to generate the word hi but with the i only being printed when the middlebutton is released. To achieve this enter the following two commands

press-array 0 middlebutton h/press sync: h/release sync:

release-array 0 middlebutton i/press sync: i/release sync:

So now we have a piece of logic which does the substitution. We can inspect it with the list-arrays command. You should see the following output

list-arrays

array[0]: record=<disabled>, play=<disabled>, state=play, permit=any, unknown=ignore

release middlebutton: i/press sync: i/release sync:

press middlebutton: h/press sync: h/release sync:

2 entries

Sofar we have something which collects the input (a source), and something which does a substitution (the array). Now we only need a sink or target. This one is easy to create. Just type start-target 0. The kernel should report a new device, called MXK/version (PID). If this doesn't work you don't have uinput support in your kernel or are missing the device node /dev/input/uinput. To check that this has been created, run the list-sources command again. You should see an extra entry

list-sources

/dev/input/event0: unused: PC Speaker

/dev/input/event1: unused: AT Translated Set 2 keyboard

/dev/input/event2: bypass: ImExPS/2 Generic Explorer Mouse

/dev/input/event3: target: MXK/0.1 (29378:0)

Admittedly, it is a bit confusing to have the target show up in the input list too, but the target is a special input device, one which mxk generates.

So we have generated the three nodes, a source, a processing node and a target. Now they need to be connected to each other in the correct way. This is done using the connect-node command. Type connect-node source:0 array:0 to connect the output of the source to the array and connect-node array:0 target:0 to connect the array output to the virtual input device. The target node then sends events back to the kernel and from there to all your applications.

This only leaves one more command - turning on the bypassed source node. Lets do it with activate-source 0. You can run used-sources or list-sources after that to see the status of the source changing from bypass to active.

Now if everything has worked out, middle clicks should also generate the word hi, try it. If it works congratulations, you have written your first mxk script.

## Cleaning up the first script
Suspend disbelief and pretend that the above mxk function is really useful and you need to run it occasionally.

To avoid typing out all the commands every time, save them to a file, say hi.mxk and then run it as follows mxk -p hi.mxk.

In case you want to run this in the background, use mxk -dzp hi.mxk.

If you prepend the line #/usr/sbin/mxk -dzp to the file hi.mxk and make it executable, then you can run the script directly, similar to a shell script.

Now before you send the script to your friend who also needs to have his middle mouse click say hi, you need to remove the hardcoded path to your mouse - currently this is set to /dev/input/event2. On your friends system the mouse is likely to show up as a different file.

There are two other ways of opening a source, by capability and by name.

Use caps-source to open a source by capability. Here a capability is the ability of a source to generate a certain event type, such as a key/button press or a relative motion event. Mice tend to have both these capabilities so use caps-source 0 key relative to open the first unused source which has these. Like in the case of the file-source and start-array commands, the 0 is the instance identifier. If you wish to list the types of events which mxk knows about, use the list-events command, while the used-sources command will show you the capabilities of already opened devices.

Alternatively you can use name-source to open the mouse by name, like this

name-source 0 ImExPS/2 Generic Explorer Mouse

Note that there are no quotes surrounding the name and that the match is case-sensitive. However, the name will match a substring, so name-source 0 ImExPS/2 would also have worked.

You may encounter hardware which registers multiple /dev/input/event entries, all having the same name. In such situations you may wish to try running a name match several times, as mxk will skip already opened sources. The below example illustrates this

list-sources

/dev/input/event0: unused: USBPS2

/dev/input/event1: unused: USBPS2

/dev/input/event2: unused: AT Translated Set 2 keyboard

3 entries

name-source 0 USBPS2

source: added source matching <USBPS2>

name-source 0 USBPS2

source: skipping /dev/input/event0: already in use

source: added source matching <USBPS2>

list-sources

/dev/input/event0: bypass: USBPS2

/dev/input/event1: bypass: USBPS2

/dev/input/event2: unused: AT Translated Set 2 keyboard

3 entries

So now you have several options to detect input devices on your friends PC. But what if your friend decides he doesn't need the script anymore and wants it stopped ?

When your friend is running mxk interactively, this is easy, just tell him to type halt.

However, when it is running as a daemon, he needs to reattach to the running instance using the command mxk -a and then type halt. This can be made noninteractive with a command such as echo halt | mxk -a.

## hi.mxk listing

\#/usr/sbin/mxk -dzp

caps-source 0 key relative

caps-source 0 key relative

start-array 0

press-array 0 middlebutton h/press sync: h/release sync:

release-array 0 middlebutton i/press sync: i/release sync:

start-target 0

connect-node source:0 array:0

connect-node array:0 target:0

activate-source 0

## Event Streams
The hi.mxk script sent events from a source to an array and from the array to the target. So what are these events ?

Linux evdev devices report an event as a triple of event type, code and value. For example, the enter keypress would belong to the key type, its code would be 28 (enter) and its value would be 1 (press) while the releasing the key would have a value of 0 (release).

mxk represents this triple as type:code/value. For example, relative:x/1 is an event reporting a small horizontal relative movement. Mice are examples of devices which generate relative movement events, while tablets tend to generate absolute movement events.

There are two shortcuts to be aware of:

☞

Where the type is left out, mxk assumes a key event, so enter/press is sufficient to describe the enter keypress.

☞

Thusfar there is only one event in the sync type, so sync: is sufficient to describe it.

The sync: event exists to group related events together. For example, relative:x/1 sync: relative:y/1 sync: moves the mouse right and then up, while relative:x/1 relative:y/1 sync: moves the mouse diagonally.

The commands

list-events

list-codes

list-relative

list-absolute

will list the known event types, key codes, relative axes and absolute axes respectively. For other event types, mxk has no symbolic names.

Note that most mxk processing nodes operate on certain event types only and tend to discard other types. In particular, many mxk processing nodes operate on keypress events only. As a matter of fact, mxk allocates an additional 256 virtual keys (virt1 to virt256) - these keys are not generated by real devices and silently discarded at the target device. They are however useful at intermediate stages. Examples of processing nodes emitting them are the timer and generic brailler nodes.

## Conditional Processing
The first example script was linear - all events which were not discarded took the same path (source to array to target).

Often it is useful to have events take different paths through the processing pipeline, or rather processing graph.

mxk provides several mechanisms to split the event stream. One such facility is the branch node. It splits the input stream into two - the uporhigh branch and the downorlow branch. The node maintains a global state variable which decides if the branch is up or down (like a railway switch). In addition, the branch node also maintains a map for each key event indicating if it may be relayed in any of the states and if it changes the state of the branch.

Lets create a branch, which toggles state whenever the left alt key is pressed. When in the up state, only relay the keys h,j,k and l. In the down state relays everything

start-branch 0

key-branch 0 h pass

key-branch 0 j pass

key-branch 0 k pass

key-branch 0 l pass

key-branch 0 leftalt toggle

default-branch 0 lopass

Now check its content

list-branches

branch[0]: state=down pattern[up]=<not set>, pattern[down]=<not set> pressed=0

default action: lopass

key h: hipass lopass

key j: hipass lopass

key k: hipass lopass

key l: hipass lopass

key leftalt: up down

5 entries

This branch could be used to enter a special mode where the h,j,k and l keys are mapped to mouse movements or arrow presses and all other keys do nothing.

So how does one connect this node to its downstream nodes ? The syntax to connect-node remains unchanged, but before connecting downstream nodes, force the branch node into the desired state. The below will connect the down branch directly to the target node, while the up branch will be connected to a remapping array

down-branch 0

connect-node branch:0 target:0

up-branch 0

connect-node branch:0 target:0

down-branch 0

Note the final down branch. It ensures that the system starts in a state where all keys are relayed.

Now imagine this node being connected to a source. What happens if the alt key is struck briefly while the h key is held down ? The simple approach of sending h/press down one branch and h/release down another is almost always likely to cause problems downstream. For this reason a branch node only changes state when all keys are released. Unfortunately not all keyboard (drivers) report the release of all keys reliably, especially after holding down several keys. This bug will then cause the branch node to stay stuck in one state. To confirm this problem the used-sources command to check if your keyboard thinks keys are depressed which are not.

The branch node is a useful facility to split a stream of events into two. But what if you wish to group events into many substreams ? While it is possible to connect several branch nodes together, there exists a node which can perform this in one go. This is the sorter node. The sorter node allows you to define a set of bins, numbered from zero and assign keypress events to a particular bin. Each bin can then be connected to a different downstream node. Do note that a particular keypress always ends up at a particular bin. This behaviour differs from a branch node where a keypress can potentially be sent down different paths, depending on the internal state of the branch node. So while it is a useful analogy to think of a branch node as being a railway switch, the sorter node functions more like a post office, where a letter with the same address should always go to the same postbox.

Lets create a sorter node with three bins, where the last bin is the default one - the one which receives all events not matched elsewhere

start-sorter 0 2

match-sorter 0 a 0

match-sorter 0 b 1

This node will categorise a into bin 0, b into bin 1 and all other keypresses, including c to bin 2.

Like the branch node, downstream nodes are connected using a plain connect-node command, but only before the bin to be connected has been selected using the bin-sorter command. For example, the following will connect bin 2 to an array.

bin-sorter 0 2

connect-node sorter:0 array

There exist a few other ways of classifying input streams, however these are not covered in the tutorial.

## Conclusion
This tutorial has provided a brief introduction to the commands which mxk uses to set up it processing graph. There exist several more processing nodes which have not yet been described here.

## See Also
mxk(8).


nagios-domain-discovery

package: nagios-domain-discovery

title: nagios-domain-discovery(8)

text:
# nagios-domain-discovery(8)

## NAME
nagios-domain-discovery - domain records to Nagios host list synchronization tool

## SYNOPSIS
nagios-domain-discovery [options]

## DESCRIPTION
nagios-domain-discovery is a tool to create and update the configuration of hosts under Nagios monitoring based on the domain records. It is configured with /etc/nagios/domain-discovery/main.conf and uses methods under /usr/lib/nagios-domain-discovery/methods.

## CONFIGURATION
/etc/nagios/domain-discovery is the main configuration directory with the main configuration file main.conf (see nagios-domain-discovery(5)). There are also could be configuration files for methods used by the tool, for instance, hostlist.conf (nagios-domain-discovery-hostlist(5)) for the simple domain record list method (see nagios-domain-discovery-hostlist(8)).

The methods are placed in /usr/lib/nagios-domain-discovery/methods directory.

## SEE ALSO
nagios-domain-discovery(5), nagios-domain-discovery-hostlist(8), nagios-domain-discovery-hostlist(5).


nagios-domain-discovery-hostlist

title: nagios-domain-discovery-hostlist(8)

summary: the simple domain record list method for nagios\-domain\-discovery tool

text:
# nagios-domain-discovery-hostlist(8)

## NAME
nagios-domain-discovery-hostlist - the simple domain record list method for nagios-domain-discovery tool

## SYNOPSIS
/usr/lib/nagios-domain-discovery/methods/hostlist

## DESCRIPTION
The hostlist method is intended to be used with the nagios-domain-discovery(8) tool. It uses host -l command to obtain the list of the hosts registered in the named (local) domain. It may not work with non-local domains.

For configuration parameters see nagios-domain-discovery-hostlist(5).

## SEE ALSO
nagios-domain-discovery-hostlist(8), nagios-domain-discovery(8), nagios-domain-discovery(5), nagios-domain-discovery-hostlist(5).


nagwad

package: nagwad-service

title: nagwad(8)

text:
# nagwad(8)

## NAME
nagwad - System journal event scanner and handler

## SYNOPSIS
nagwad [options] [command]

## DESCRIPTION
Daemon that continuously reads the system journal and generates events based on journal messages. The example configuration contains templates to pass the events further to Icinga and Nagios.

To run as a system service use:

nagwad --service

To list registered events use the list command:

nagwad [list]

To view one particular event use the show command:

nagwad [show] EVENT-ID

To mark an event as fixed use the fix command:

nagwad fix EVENT-ID [EVENT-ID ...]

To check all or some events use the check command:

nagwad check [FILTER]

To check for the nagwad service status use the status command:

nagwad status

To cleanup events from older system boots use the clean-old command:

nagwad cleanup-old [DAYS]

Note, that the time intervals are truncated to integer numbers. So, in order to be deleted, the log directory has to be DAYS + 1 days older.

To run in the test mode use (reading messages from standard input):

nagwad --test

To run with alternative configuration file use:

nagwad -c CONF | --config=CONF

## CONFIGURATION FILES
/etc/nagwad/nagwad.conf

/etc/sysconfig/nagwad (overrides values set in /etc/nagwad/nagwad.conf)

/etc/nagwad/*.regexp

/etc/nagwad/*.sed

/etc/nagwad/filter-event.d/*

/etc/nagwad/process-event.d/*

## BUGS
Report bugs to https://bugzilla.altlinux.org/.

## COPYRIGHT
Copyright © BaseALT, Ltd. License GPLv2+: GNU GPL version 3 or later See <http://gnu.org/licenses/gpl.html> for more information.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
/usr/share/doc/nagwad-service-0.11.10/README.html

/usr/share/doc/nagwad-service-0.11.10/signal.html


nbd-client

package: nbd-client

title: nbd-client(8)

text:
# nbd-client(8)

## NAME
nbd-client - connect to a server running nbd-server(1), to use its exported block device

## SYNOPSIS
nbd-client host [ port ] nbd-device [ -connections num ] [ -sdp ] [ -swap ] [ -persist ] [ -nofork ] [ -nonetlink ] [ -systemd-mark ] [ -readonly ] [ -preinit ] [ -block-size block size ] [ -size bytes ] [ -timeout seconds ] [ -name name ] [ -certfile certfile ] [ -keyfile keyfile ] [ -cacertfile cacertfile ] [ -tlshostname hostname ] [ -priority gnutls-priority-string ]

nbd-client -unix path nbd-device [ -connections num ] [ -sdp ] [ -swap ] [ -persist ] [ -nofork ] [ -nonetlink ] [ -systemd-mark ] [ -readonly ] [ -preinit ] [ -block-size block size ] [ -size bytes ] [ -timeout seconds ] [ -name name ]

nbd-client nbd-device

nbd-client -d nbd-device

nbd-client -c nbd-device

nbd-client -l host [ port ]

nbd-client [ -netlink ] -l host

## DESCRIPTION
With nbd-client, you can connect to a server running nbd-server, thus using raw diskspace from that server as a blockdevice on the local client.

To do this, support from the Linux Kernel is necessary, in the form of the Network Block Device (NBD). When you have that, either in the kernel, or as a module, you can connect to an NBD server and use its exported file through a block special file with major mode 43.

Optionally, long options can also be specified with two leading dashes.

## OPTIONS
The following options are supported:

-block-size block size

-b

Use a blocksize of "block size". Default is 512; allowed values are either 512, 1024, 2048 or 4096

-connections num

-C

Use num connections to the server, to allow speeding up request handling, at the cost of higher resource usage on the server. Use of this option requires kernel support available first with Linux 4.9.

host

The hostname or IP address of the machine running nbd-server. Since 2.9.15, the NBD utilities support IPv6.

-timeout

-t

Set the connection timeout to "seconds". For this to work, you need a kernel with support for the NBD_SET_TIMEOUT ioctl; this was introduced into Linus' tree on 2007-10-11, and will be part of kernel 2.6.24.

port

The TCP port on which nbd-server is running at the server. The port number defaults to 10809, the IANA-assigned port number for the NBD protocol.

Previous versions of the nbd tools supported an older version of the negotiation protocol known as "oldstyle". This protocol version is no longer supported as of version 3.11 of the nbd support tools.

nbd-device

The block special file (/dev entry) which this nbd-client should connect to, specified as a full path. When the mode is used wherein no hostname or export name is specified, nbd-client will look up the necessary configuration in the nbdtab file. For more information, see nbdtab(5).

-check

-c

Check whether the specified nbd device is connected. If the device is connected, nbd-client will exit with an exit state of 0 and print the PID of the nbd-client instance that connected it to stdout.

If the device is not connected or does not exist (for example because the nbd module was not loaded), nbd-client will exit with an exit state of 1 and not print anything on stdout.

If an error occurred, nbd-client will exit with an exit state of 2, and not print anything on stdout either.

-disconnect

-d

Disconnect the specified nbd device from the server

-list

-l

Ask the server for a list of available exports. If the server is exporting over IPv6 as well as over IPv4, this will list all exports twice; otherwise, it should list them all only once. Note that this option only works with nbd-server processes running version 3.1 or above, and must be enabled in server configuration (with the "allowlist" option) before it can be used.

-nonetlink

-L

Starting with version 3.17, nbd-client will default to using the netlink interface to configure an NBD device. This option allows to use the older ioctl() interface to configure the device. This option is only available if nbd-client was compiled against libnl-genl. If that is not the case, nbd-client will only be able to use the ioctl interface (and the option will not be available).

Note that a future version of nbd-client will require the use of netlink, but it has not yet been decided when that will be the case.

-identifier ident

-i

Added in 3.27, this tells nbd-client to set the netlink identifier (requires kernel 5.14 or newer), which can later be viewed at /sys/block/nbdN/backend. This prevents any process from using netlink to silently reconfigure the device to a different backend, making it easier to write idempotent code that is safe in the presence of configuration races. This option is only available if nbd-client was compiled against libnl-genl. If that is not the case, nbd-client will only be able to use the ioctl interface (and the option will not be available).

Note that a future version of nbd-client will require the use of netlink, but it has not yet been decided when that will be the case.

-persist

-p

When this option is specified, nbd-client will immediately try to reconnect an nbd device if the connection ever drops unexpectedly due to a lost server or something similar.

-preinit

-P

When this option is specified, nbd-client will skip the usual negotiation with the server, and hand the socket to the kernel immediately after connecting. Only use this when connecting to specialized NBD servers specifically designed for it. This requires specifying the size of the device via the -B option, and does not support TLS.

-readonly

-R

When this option is specified, nbd-client will tell the kernel to treat the device as read-only, even if the server would allow writes.

-size bytes

-B bytes

Force the device size to the specified number of bytes, rather than using the value from server negotiation. Must be a multiple of the block size. If using preinit (-P) to skip negotiation, this option is required.

-sdp

-S

Connect to the server using the Socket Direct Protocol (SDP), rather than IP. See nbd-server(5) for details.

-swap

-s

Specifies that this NBD device will be used as swapspace. This option attempts to prevent deadlocks by performing mlockall() and adjusting the oom-killer score at an appropriate time. It does not however guarantee that such deadlocks can be avoided.

-systemd-mark

-m

The systemd init system requires that processes which should not be killed at shutdown time be marked appropriately by replacing the first letter of their argv[0] with an '@' sign. This option will cause nbd-client to do so.

Note that this only works if nbd-client is run from an initrd; i.e., systemd will ignore such a mark if run from a systemd unit file or from the command line.

-nofork

-n

Specifies that the NBD client should not detach and daemonize itself. This is mostly useful for debugging. Note that nbd-client will still fork once to trigger an update to the device node's partition table. It is not possible to disable this.

-no-optgo

-g

Disable the use of the NBD_OPT_GO protocol message, and force the use of NBD_OPT_EXPORT_NAME instead. The NBD protocol has two phases: the negotiation phase, and the transmission phase. To move from negotation to transmission, older clients sent the NBD_OPT_EXPORT_NAME message, for which the server could not produce an error message in case the export name did not exist (or the client had insufficient permissions to access it). Due to those limitations, a replacement message NBD_OPT_GO was created instead, which allows the server to reply with an error in case of any problems.

The protocol allows for a server to discard a message which it does not understand; however, unfortunately some implementations (including older versions of nbd-server) did not handle that situation correctly and would get out of sync with the client when it sent a message which the server did not understand.

When sending NBD_OPT_GO, nbd-client will try to do the right thing and fall back to NBD_OPT_EXPORT_NAME. However, when the server has the above-described bug, then this does not work. In such a situation, the client will issue a diagnostic suggesting the use of this option.

Note that there is a corresponding option for nbdtab, too.

-name

-N

Specifies the name of the export that we want to use. If not specified, nbd-client will ask for a "default" export, if one exists on the server.

-unix

-u

Connect to the server over a unix domain socket at path, rather than to a server over a TCP socket. The server must be listening on the given socket.

-certfile file

-F

Use the specified file as the client certificate for TLS authentication to the server.

-keyfile file

-K

Use the specified file as the private key for the client cerificate.

-cacertfile file

-A

Use the specified file as the CA certificate for TLS authentication to the server.

-tlshostname hostname

-H

Use the specified hostname for the TLS context. If not specified, the hostname used to connect to the server will be used.

-priority gnutls priority string

-y

Pass the specified priority string to GnuTLS. This can be used to configure the TLS connection; see the GnuTLS documentation for details. The default value for this option is NORMAL:-VERS-TLS-ALL:+VERS-TLS1.2.

### TLS SUPPORT
Enabling any of the TLS-related options causes the client to use the NBD_OPT_STARTTLS command to upgrade the connection to TLS. Since negotiating TLS support from userspace for a kernel socket would be very involved (if passing keys to kernel space were even possible, which it isn't), the way this is implemented is that the nbd-client process creates a socketpair, one side of which it hands to the kernel, and the other side of which is handed to an encrypting/decrypting proxy. This has the effect that all communication will be encrypted before being sent over the wire; however, doing so is not safe in combination with swapping over an NBD device:

In order to free memory by swapping, the kernel needs to be sure that the write to the nbd device has finalized. For this, it needs to be able to receive an NBD_CMD_WRITE reply which informs it that the write has completed successfully and that the memory may be released. Receiving data over the network, however, requires that the kernel allocate memory first, which is impossible if we're low on memory (a likely situation when trying to swap). This is likely to cause a deadlock when we're low on memory and there are high amounts of network traffic.

To remedy this situation, the kernel sets the PF_MEMALLOC option on the nbd socket; when low on memory, it will throw away all packets except for those destined to a socket with that option set, relying on the normal TCP retransmit system to ensure that data is not lost. This avoids the deadlock described above.

However, the PF_MEMALLOC option is set on the socket that is connected to the nbd device, not the encrypted socket connected to the encrypting/decrypting proxy. As such, when using TLS, the PF_MEMALLOC option is not set on the socket that actually receives data from the network, which means that the deadlock reappears.

For this reason, if the -swap option is used when TLS is in use, nbd-client will issue an appropriate warning.

## EXAMPLES
Some examples of nbd-client usage:

•

To connect to a server running on port 2000 at host "server.domain.com", using the client's block special file "/dev/nbd0": nbd-client server.domain.com 2000 /dev/nbd0

•

To connect to a server running on port 2001 at host "swapserver.domain.com", using the client's block special file "/dev/nbd1", for swap purposes: nbd-client swapserver.domain.com 2001 /dev/nbd1 -swap

•

To disconnect the above connection again (after making sure the block special file is not in use anymore): nbd-client -d /dev/nbd1

## SEE ALSO
nbd-server (1).

## AUTHOR
The NBD kernel module and the NBD tools have been written by Pavel Macheck (pavel@ucw.cz).

The kernel module is now maintained by Paul Clements (Paul.Clements@steeleye.com), while the userland tools are maintained by Wouter Verhelst (wouter@debian.org)

This manual page was written by Wouter Verhelst (<wouter@debian.org>) for the Debian GNU/Linux system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.


title: ndisc6(8)

summary: ICMPv6 Neighbor Discovery tool

text:
# ndisc6(8)

## NAME
ndisc6 - ICMPv6 Neighbor Discovery tool

## SYNOPSIS
ndisc6 [-1mnqv] [-r attempts] [-s source_ip] [-w wait_ms] <IPv6 address> <iface>

## DESCRIPTON
NDisc6 is an Unix program which implements the ICMPv6 Neighbor Discovery in userland (it is normally done by the kernel). It is used to lookup the link-layer address (layer 2 address, MAC in the case of Ethernet) of any on-link IPv6 node.

The IPv6 address of the node must be specified, as well as the networking interface on which to perform the lookup.

## OPTIONS
-1 or --single

Exit as soon as the first advertisement is received (default).

-h or --help

Display some help and exit.

-m or --multiple

Wait for possible duplicate advertisements and print all of them.

-n or --numeric

If the first parameter is not a valid IPv6 address, do not try to resolve it as a DNS hostname.

-q or --quiet

Only display link-layer address. Display nothing in case of failure. That is mostly useful when calling the program from a shell script.

-r attempts or --retry attempts

Send ICMPv6 Neighbor Discovery that many times until a reply is received, or abort. By default, ndisc6 will try 3 times before aborting (MAX_MULTICAST_SOLICIT and MAX_UNICAST_SOLICIT from RFC2461).

-s source_ip or --source source_ip

Specify the IPv6 address to be used as the source for the neighbor solicitation packets.

-V or --version

Display program version and license and exit.

-v or --verbose

Display verbose information. That is the default.

-w wait_ms or --wait wait_ms

Wait wait_ms milliseconds for a response before retrying. By default, ndisc6 waits 1 second between each attempts (RETRANS_TIMER from RFC2461).

If ndisc6 does not receive any response after the specified number of attempts waiting for wait_ms milliseconds each time, it will exit with code 2. On error, it exits with code 1. Otherwise it exits with code 0. This makes it possible to use the exit code to see if a host is on-link or not.

## DIAGNOSTICS
If you get no response while you know the remote host is up, it is most likely that it is not on-link, that is to say, you must cross one or more routers to reach it. By design, IPv6 nodes ignore ICMPv6 Neighbor Discovery packets received from nodes not on the same link (i.e. Ethernet segment), for the sake of security. Technically, that is done by ensuring that the Hop limit (TTL) is 255.

Note that you cannot use ndisc6 to lookup the local host's link-layer address.

## SECURITY
ndisc6 should be setuid root to allow use by non-privileged users. It will drop its root privileges before any attempt is made to send or receive data from the network to reduce the possible impact of a security vulnerability.

## SEE ALSO
ping6(8), rdisc6(8), ipv6(7)

## AUTHOR
Rémi Denis-Courmont <remi at remlab dot net>

http://www.remlab.net/ndisc6/


title: rdisc6(8)

summary: ICMPv6 Router Discovery tool

text:
# rdisc6(8)

## NAME
rdisc - ICMPv6 Router Discovery tool

## SYNOPSIS
rdisc6 [-qv] [-r attempts] [-s source_ip] [-w wait_ms] [IPv6 address] <iface>

## DESCRIPTON
RDisc6 is an Unix program which implements the ICMPv6 Router Discovery in userland (it is normally done by the kernel). It is used to lookup the list of on-link routers and IPv6 prefixes.

It can also be used to force the kernel to update the state of a given IPv6-autoconfigured network interface.

The name of the network interface to probe routers for must be specified.

## OPTIONS
-1 or --single

Exit as soon as the first advertisement is received.

-h or --help

Display some help and exit.

-m or --multiple

Wait for possible multiple advertisements and print all of them (default).

-n or --numeric

If the optional parameter is not a valid IPv6 address, do not try to resolve it as a DNS hostname.

-q or --quiet

Only display advertised IPv6 prefixes. Display nothing in case of failure. That is mostly useful when calling the program from a shell script.

-r attempts or --retry attempts

Send ICMPv6 Router Discovery that many times until a reply is received, or abort. By default, rdisc6 will try 3 times before aborting (MAX_RTR_SOLICITATIONS from RFC2461).

-s source_ip or --source source_ip

Specify the IPv6 address to be used as the source for the router solicitation packets.

-V or --version

Display program version and license and exit.

-v or --verbose

Display verbose information. That is the default.

-w wait_ms or --wait wait_ms

Wait wait_ms milliseconds for a response before retrying. By default, rdisc6 waits 4 second between each attempts (RTR_SOLICITATION_INTERVAL from RFC2461).

If rdisc6 does not receive any response after the specified number of attempts waiting for wait_ms milliseconds each time, it will exit with code 2. On error, it exits with code 1. Otherwise it exits with code 0.

## SECURITY
rdisc6 must be setuid root to allow use by non privileged users. It will drop its root privileges before any attempt is made to send or receive data from the network to reduce the possible impact of a security vulnerability.

## SEE ALSO
ndisc6(8), ipv6(7)

## AUTHOR
Rémi Denis-Courmont <remi at remlab dot net>

http://www.remlab.net/ndisc6/


title: rltraceroute6(8)

summary: IPv6 traceroute tool

text:
# rltraceroute6(8)

## NAME
rltraceroute6 - IPv6 traceroute tool

tcptraceroute6 - TCP/IPv6 traceroute tool

## SYNOPSIS
traceroute6 [-AdEILlnrSU] [-f min_hop] [-g hop] [ -i iface] [-m max_hop] [-p port] [-q attempts] [ -s source] [-t tclass] [-w wait] [-z delay_ms] < hostname/address> [packet length]

tcptraceroute6 [-AdEnrS] [-f min_hop] [-g hop] [ -i iface] [-l packet_size] [-m max_hop] [-p port] [ -q attempts] [-s source] [-t tclass] [-w wait] [ -z delay_ms] < hostname/address> [port]

## DESCRIPTON
rltraceroute6 is an IPv6 traceroute implementation.

It displays the list of hops along the network route between the local system and specified destination, by sending packets while incrementing their hop limit, until the final destination is reached.

By default, rltraceroute6 sends UDP probe packets toward the destination (that's the historical default). However, it can also send TCP packets, much like Michael C. Toren's tcptraceroute does on IPv4 networks; tcptraceroute6 sends TCP packets by default (and mimics tcptraceroute command line syntax). Finally, it can also send ICMPv6 Echo Request packets, like some other traceroute implementations (such as the one in Microsoft Windows); tracert6 does this by default.

You must specify the name or address of the host toward which the network route should be determined. An optional additional parameter specifies either the probe packets length (for UDP and ICMP packets), or the destination port number/service name (for TCP packets).

Note that TCP destination port zero really is TCP port numbered 0 (which cannot be used via the standard higer-level TCP/IP programming interface).

## OPTIONS
-A

Send TCP/ACK probe packets. That's very efficient against stateless firewalls (e.g. the official Linux kernel versions up to and including 2.4.31 and 2.6.14), and utterly helpless against stateful ones. Note that TCP/ACK probing cannot determine whether the destination TCP port is open or not.

-d

Enable socket debugging option (SO_DEBUG). Unless you are debugging the kernel, this is probably not going to have any actual effect.

-E

Send ECN-setup TCP/SYN probe packets (as per RFC 3168) rather than non-ECN-setup TCP/SYN probe packets. This has no effect unless command line optin -S is specified as well.

-F

This option is ignored for backward compatibility. IPv6 packets are never fragmented en route.

-f

Override the initial IPv6 packets hop limit (default: 1).

-g

Add an IPv6 route segment within an IPv6 Routing Header. This enables loose source routing. Currently, only "Type 0" routing header is supported.

-h

Display some help and exit.

-I (rltraceroute6 only)

Send ICMPv6 Echo requests (like ping6) as probe packets. That's the default for tracert6.

-i

Only send packets through the specified interface. See also BUGS.

-I (rltraceroute6 only)

Send UDP-Lite (protocol 136) packets (with full checksum coverage) as probe packets instead of normal UDP (protocol 17).

-l (rltraceroute6 only)

Print the hop limit of received packets. This is mostly used to detect asymmetric routing.

-l (tcptraceroute6 only)

Specify the size (bytes) of sent packets.

-m

Override the maximum hop limit (maximum number of hops). The default is 30 hops which should be sufficient on the IPv6 Internet for some time.

-N

Try to resolve each hop's IPv6 address to a host name. This is the default. This option is meant for backward compatibility with tcptraceroute(8).

-n

Do not try to resolve each hop's IPv6 address to a host name. That may speed up the traceroute significantly.

-p

For rltraceroute6, specify the base destination port number (default: 33434). rltraceroute6 assumes that packets toward this port up to this port plus the maximum hop limit are not in use by any program on the final destination and that they are not blocked by some firewall. The fact that this very assumption was not always correct, eventually lead to the development of the original IPv4 tcptraceroute by Michael Toren. For tcptraceroute6, specify the source port number (default: auto). Note that source port number zero really means number zero, rather than some port number that would be automatically assigned, as is the case with usual softwares.

-q

Override the number of probes sent to each hop (default: 3).

-r

Do not route packets, i.e. do not send packets through a gateway that would be specified by the routing table. See also BUGS.

-S

Use TCP/SYN probe packets. That's the default for tcptraceroute6.

-s

Specify the source address to use for probe packets explicitly.

-S

Use UDP probe packets. That's the default for rltraceroute6.

-t

Specify the traffic class (DSCP) for probe packets. See also BUGS.

-U (rltraceroute6 only)

Send UDP probe packets. That's the default.

-V

Display program version and license and exit.

-w

Override the delay (in seconds) to wait for response once a given probe packet was sent (default: 5 seconds).

-x

This option is ignored for seamless migration from IPv4 traceroute. The IPv6 header has no checksum field.

-z

Specify a milliseconds delay to wait between each probe with identical hop limit. This can be useful to work-around ICMPv6 rate limitation on some hosts.

## DIAGNOSTICS
If a response is received, the round-trip time is printed. In addition, specific symbols denote certain errors:

* No response

No valid response received before the timeout delay (see -w option).

!N No route to destination

There is no entry for the destination network in the routing table.

!A Communication with destination administratively prohibited

A firewall explicitly rejected the traffic.

!S Beyond scope of source address

The address scope of the source address is too small to reach the destination address. At the time of writing, this can only happen when using a link-local source address to reach a global scope destination. (Note: some IPv4 traceroute implementations use !S for source route error which is completely different)

!H Address unreachable

The host address is not reachable for some other reasons, particularly a link-layer failure (e.g. Neighbor discovery failure).

!P Unrecognized Next Header type encountered

The destination does not implement the layer-4 protocol used. You should retry with ICMPv6 Echo Requests (-I command line option) which MUST be supported by any IPv6 node.

## SECURITY
rltraceroute6 should be setuid root to allow use by non privileged users. It will drop its root privileges before any attempt is made to send or receive data from the network so as to reduce the possible impact of a security vulnerability.

## BUGS
However useful they might be, -i and -r options are ignored by the official Linux kernel at the time of writing this manpage, and hence do not work as documented.

Support for option -t was broken until Linux kernel version 2.6.18.

Usage of Routing Header, with option -g, triggers an OOPS on Linux kernel versions below 2.6.17.12.

Receiving TCP/SYN-ACK packets does not work on FreeBSD at all. This severely limits the usefulness of tcptraceroute6 on FreeBSD.

Packet length takes the IPv6 header and, if present, extension headers into account. rltraceroute6 versions before 0.7.4 used it as IPv6 payload length instead, i.e. did not include the layer-3 headers in the computation. Linux iputils traceroute6 does not even include the UDP header. On the whole, the packet length semantic is very inconsistent among IPv6 traceroute implementations.

## SEE ALSO
ipv6(7), traceroute(8), tcptraceroute(8), traceroute6(8)

## AUTHOR
Rémi Denis-Courmont <remi at remlab dot net>

http://www.remlab.net/ndisc6/


loadndisdriver

package: ndiswrapper

title: loadndisdriver(8)

text:
# loadndisdriver(8)

## NAME
loadndisdriver - Userspace ndis driver loader for the ndiswrapper Linux kernel module

## SYNOPSIS
loadndisdriver

## DESCRIPTION
loadndisdriver is a support program for the ndiswrapper Linux kernel module. The ndiswrapper kernel module uses it to load ndis drivers that have been installed via the ndiswrapper(8) tool.

loadndisdriver should not be used directly, only the kernel module should use it. Therefore, it's options are volatile, and subject to change during the development of the ndiswrapper kernel module.

The /etc/ndiswrapper directory is expected to contain the ndis files that loadndisdriver requires.

## SEE ALSO
ndiswrapper(8)

## AUTHOR
This manual page was written by Kel Modderman <kelrin@tpg.com.au>, for the Debian project (but may be used by others).