mu-easy

package: mu

title: mu-easy(7)

text:
# mu-easy(7)

## NAME
mu easy - a quick introduction to mu

## DESCRIPTION
mu is a set of tools for dealing with e-mail messages in Maildirs. There are many options, which are all described in the man pages for the various sub-commands. This man pages jumps over all of the details and gives examples of some common use cases. If the use cases described here do not precisely do what you want, please check the more extensive information in the man page about the sub-command you are using -- for example, the mu-index(1) or mu-find(1) man pages.

NOTE: the index command (and therefore, the ones that depend on that, such as find), require that you store your mail in the Maildir-format. If you don't do so, you can still use the other commands, but you won't be able to index/search your mail.

By default, mu uses colorized output when it thinks your terminal is capable of doing so. If you don't like color, you can use the --nocolor command-line option, or set either the MUNOCOLOR or the NOCOLOR environment variable to non-empty.

## SETTING THINGS UP
The first time you run the mu commands, you need to initialize it. This is done with the init command.

```
$ mu init
```

This uses the defaults (see mu-init(1) for details on how to change that).

## INDEXING YOUR E-MAIL
Before you can search e-mails, you'll first need to index them:

```
$ mu index
```

The process can take a few minutes, depending on the amount of mail you have, the speed of your computer, hard drive etc. Usually, indexing should be able to reach a speed of a few hundred messages per second.

mu index guesses the top-level Maildir to do its job; if it guesses wrong, you can use the --maildir option to specify the top-level directory that should be processed. See the *mu-index*(1) man page for more details.

Normally, mu index visits all the directories under the top-level Maildir; however, you can exclude certain directories (say, the 'trash' or 'spam' folders) by creating a file called .noindex in the directory. When mu sees such a file, it will exclude this directory and its sub-directories from indexing. Also see .noupdate in the *mu-index*(1) manpage.

## SEARCHING YOUR E-MAIL
After you have indexed your mail, you can start searching it. By default, the search results are printed on standard output. Alternatively, the output can take the form of Maildir with symbolic links to the found messages. This enables integration with e-mail clients; see the *mu-find*(1) man page for details, the syntax of the search parameters and so on. Here, we just give some examples for common cases.

You can use the mu fields command to get information about all possible fields and flags.

First, let's search for all messages sent to Julius (Caesar) regarding fruit:

```
$ mu find t:julius fruit
```

This should return something like:

```
2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
```

This means there is a message to 'julius' with 'fruit' somewhere in the message. In this case, it's a message from John Milton. Note that the date format depends on your the language/locale you are using.

How do we know that the message was sent to Julius Caesar? Well, it's not visible from the results above, because the default fields that are shown are date/sender/subject. However, we can change this using the --fields parameter (try mu fields to see all the details):

```
$ mu find --fields="t s" t:julius fruit
```

In other words, display the 'To:'-field (t) and the subject (s). This should return something like:

```
Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
```

This is the same message found before, only with some different fields displayed.

By default, mu uses the logical AND for the search parameters -- that is, it displays messages that match all the parameters. However, we can use logical OR as well:

```
$ mu find t:julius OR f:socrates
```

In other words, display messages that are either sent to Julius Caesar or are from Socrates. This could return something like:

```
2008-07-31T21:57:25 EEST Socrates <soc@example.com> cool stuff
2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
```

What if we want to see some of the body of the message? You can get a 'summary' of the first lines of the message using the --summary-len option, which will

```
$ mu find --summary-len=3 napoleon m:/archive
```

```
1970-01-01T02:00:00 EET Napoleon Bonaparte <nb@example.com> rock on dude
Summary: Le 24 février 1815, la vigie de Notre-Dame de la Garde signala le
trois-mâts le Pharaon, venant de Smyrne, Trieste et Naples. Comme
d'habitude, un pilote côtier partit aussitôt du port, rasa le château
```

The summary consists of the first n lines of the message with all superfluous whitespace removed.

Also note the m:/archive parameter in the query. This means that we only match messages in a maildir called '/archive'.

## MORE QUERIES
Let's list a few more queries that may be interesting; please note that searches for message flags, priority and date ranges are only available in mu version 0.9 or later.

Get all important messages which are signed:

```
*$ mu find flag:signed prio:high *
```

Get all messages from Jim without an attachment:

```
*$ mu find from:jim AND NOT flag:attach*
```

Get all messages where Jack is in one of the contact fields:

```
*$ mu find contact:jack*
```

This uses the special contact: pseudo-field which matches (from, to, cc and bcc).

Get all messages in the Sent Items folder about yoghurt:

```
*$mu find maildir:'/Sent Items' yoghurt*
```

Note how we need to quote search terms that include spaces.

Get all unread messages where the subject mentions Ångström:

```
*$ mu find subject:Ångström flag:unread*
```

which is equivalent to:

```
*$ mu find subject:angstrom flag:unread*
```

because does mu is case-insensitive and accent-insensitive.

Get all unread messages between March 2002 and August 2003 about some bird (or a Swedish rock band):

```
*$ mu find date:20020301..20030831 nightingale flag:unread*
```

Get all messages received today:

```
*$ mu find date:today..now*
```

Get all messages we got in the last two weeks about emacs:

```
*$ mu find date:2w..now emacs*
```

Another powerful feature (since 0.9.6) are wildcard searches, where you can search for the last n characters in a word. For example, you can search for:

```
*$ mu find 'subject:soc*'*
```

and get mails about soccer, Socrates, society, and so on. Note, it's important to quote the search query, otherwise the shell will interpret the '*'.

You can also search for messages with a certain attachment using their filename, for example:

```
*$ mu find 'file:pic*'*
```

will get you all messages with an attachment starting with 'pic'.

If you want to find attachments with a certain MIME-type, you can use the following:

Get all messages with PDF attachments:

```
*$ mu find mime:application/pdf*
```

or even:

Get all messages with image attachments:

```
*$ mu find 'mime:image/*'*
```

Note that (1) the '' wildcard can only be used as the rightmost thing in a search query, and (2) that you need to quote the search term, because otherwise your shell will interpret the '' (expanding it to all files in the current directory -- probably not what you want).

## DISPLAYING MESSAGES
We might also want to display the complete messages instead of the header information. This can be done using mu view command. Note that this command does not use the database; you simply provide it the path to a message.

Therefore, if you want to display some message from a search query, you'll need its path. To get the path (think *l*ocation) for our first example we can use:

```
$ mu find --fields="l" t:julius fruit
```

And we'll get something like:

```
/home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
```

We can now display this message:

```
$ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
From: John Milton <jm@example.com>
To: Julius Caesar <jc@example.com>
Subject: Fere libenter homines id quod volunt credunt
Date: 2008-07-31T21:57:25 EEST
OF Mans First Disobedience, and the Fruit
Of that Forbidden Tree, whose mortal taste
Brought Death into the World, and all our woe,
[...]
```

## FINDING CONTACTS
While mu find searches for messages, there is also mu cfind to find contacts, that is, names + addresses. Without any search expression, mu cfind lists all of your contacts.

```
$ mu cfind julius
```

will find all contacts with 'julius' in either name or e-mail address. Note that mu cfind accepts a regular expression (as per pcre(3))

mu cfind also supports a --format=-parameter, which sets the output to some specific format, so the results can be imported into another program. For example, to export your contact information to a mutt address book file, you can use something like:

```
$ mu cfind --format=mutt-alias > ~/mutt-aliases
```

Then, you can use them in mutt if you add something like source ~/mutt-aliases to your muttrc.

## REPORTING BUGS
Please report bugs at https://github.com/djcb/mu/issues.

## AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

## COPYRIGHT
This manpage is part of mu 1.10.7.

Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
mu(1), mu-init(1), mu-index(1), mu-find(1), mu-mfind(1), mu-mkdir(1), mu-view(1), mu-extract(1)


mu-query

title: mu-query(7)

text:
# mu-query(7)

## NAME
mu query language -- a language for finding messages in mu databases.

## DESCRIPTION
The mu query language is a language used by mu find and mu4e to find messages in mu's Xapian databases. The language is quite similar to Xapian's default query-parser, but is an independent implementation that is customized for the mu/mu4e use-case.

In this article, we give a structured but informal overview of the query language and provide examples.

As a companion to this, we recommend the mu fields and mu flags commands to get an up-to-date list of the available fields and flags.

NOTE: if you use queries on the command-line (say, for mu find), you need to quote any characters that would otherwise be interpreted by the shell, such as "", ( and ) and whitespace.

## TERMS
The basic building blocks of a query are terms; these are just normal words like to just that field. See mu find for all the available fields.

Some example queries:

```
vacation
subject:capybara
maildir:/inbox
```

Terms without an explicit field-prefix, (like 'vacation' above) are interpreted like:

```
to:vacation or subject:vacation or body:vacation or ...
```

The language is case-insensitive for terms and attempts to 'flatten' any diacritics, so angtrom matches Ångström.

If terms contain whitespace, they need to be quoted:

```
subject:"hi there"
```

This is a so-called phrase query, which means that we match against subjects that contain the literal phrase "hi there".

Remember that you need to escape those quotes when using this from the command-line:

```
mu find subject:\"hi there\"
```

## LOGICAL OPERATORS
We can combine terms with logical operators -- binary ones: and, or, xor and the unary not, with the conventional rules for precedence and association, and are case-insensitive.

You can also group things with ( and ), so you can do things like:

```
(subject:beethoven or subject:bach) and not body:elvis
```

If you do not explicitly specify an operator between terms, and is implied, so the queries

```
subject:chip subject:dale
```

```
subject:chip AND subject:dale
```

are equivalent. For readability, we recommend the second version.

Note that a pure not - e.g. searching for not apples is quite a 'heavy' query.

## REGULAR EXPRESSIONS AND WILDCARDS
The language supports matching basic PCRE regular expressions, see pcre(3).

Regular expressions are enclosed in //. Some examples:

```
subject:/h.llo/		# match hallo, hello, ...
subject:/
```

Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the former matches messages in the '/foo' maildir, while the latter matches all messages in all maildirs that match 'foo', such as '/foo', '/bar/cuux/foo', '/fooishbar' etc.

Wildcards are an older mechanism for matching where a term with a rightmost * (and only in that position) matches any term that starts with the part before the *; they are supported for backward compatibility and mu translates them to regular expressions internally:

```
foo*
```

is equivalent to

```
/foo.*/
```

As a note of caution, certain wild-cards and regular expression can take quite a bit longer than 'normal' queries.

## FIELDS
We already saw a number of search fields, such as subject: and body:. For the full table, see mu-fields(1).

```
bcc,h           Bcc (blind-carbon-copy) recipient(s)
body,b          Message body
cc,c            Cc (carbon-copy) recipient(s)
changed,k       Last change to message file (range)
date,d          Send date (range)
embed,e         Search inside embedded text parts
file,j          Attachment filename
flag,g          Message Flags
from,f          Message sender
list,v          Mailing list (e.g. the List-Id value)
maildir,m       Maildir
mime,y          MIME-type of one or more message parts
msgid,i         Message-ID
prio,p          Message priority (=low=, =normal= or =high=)
size,z          Message size range
subject,s       Message subject
tag,x           Tags for the message
thread,w        Thread a message belongs to
to,t            To: recipient(s)
```

The shortcut character can be used instead of the full name:

```
f:foo@bar
```

is the same as

```
from:foo@bar
```

For queries that are not one-off, we would recommend the longer name for readability.

There are also the special fields contact:, which matches all contact-fields (from, to, cc and bcc), and recip, which matches all recipient-fields (to, cc and bcc). Hence, for instance,

```
contact:fnorb@example.com
```

is equivalent to

```
(from:fnorb@example.com or to:fnorb@example.com or

      cc:from:fnorb@example.com or bcc:fnorb@example.com)
```

## DATE RANGES
The date: field takes a date-range, expressed as the lower and upper bound, separated by ... Either lower or upper (but not both) can be omitted to create an open range.

Dates are expressed in local time and using ISO-8601 format (YYYY-MM-DD HH:MM:SS); you can leave out the right part, and mu adds the rest, depending on whether this is the beginning or end of the range (e.g., as a lower bound, end of the year).

You can use '/' , '.', '-' and 'T' to make dates more human readable.

Some examples:

```
date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016
```

You can also use the special 'dates' now and today:

```
date:20170505..now
date:today..
```

Finally, you can use relative 'ago' times which express some time before now and consist of a number followed by a unit, with units s for seconds, M for minutes, h for hours, d for days, w for week, m for months and y for years. Some examples:

```
date:3m..
date:2017.01.01..5w
```

## SIZE RANGES
The size or z field allows you to match size ranges -- that is, match messages that have a byte-size within a certain range. Units (b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are supported). Some examples:

```
size:10k..2m
size:10m..
```

## FLAG FIELD
The flag/g field allows you to match message flags. The following fields are available:

```
a,attach        Message with attachment
d,draft         Draft Message
f,flagged       Flagged
l,list          Mailing-list message
n,new           New message (in new/ Maildir)
p,passed        Passed ('Handled')
r,replied       Replied
s,seen          Seen
t,trashed       Marked for deletion
u,unread        new OR NOT seen
x,encrypted     Encrypted message
z,signed        Signed message
```

Some examples:

```
flag:attach
flag:replied
g:x
```

Encrypted messages may be signed as well, but this is only visible after decrypting and thus invisible to mu.

## PRIORITY FIELD
The message priority field (prio:) has three possible values: low, normal or high. For instance, to match high-priority messages:

```
prio:high
```

## MAILDIR
The Maildir field describes the directory path starting after the Maildir-base path, and before the /cur/ or /new/ part. So for example, if there's a message with the file name ~/Maildir/lists/running/cur/1234.213:2,, you could find it (and all the other messages in the same maildir) with:

```
maildir:/lists/running
```

Note the starting ''. If you want to match mails in the 'root' maildir, you can do with a single '':

```
maildir:/
```

If you have maildirs (or any fields) that include spaces, you need to quote them, ie.

```
maildir:"/Sent Items"
```

Note that from the command-line, such queries must be quoted:

```
mu find 'maildir:"/Sent Items"'
```

## MORE EXAMPLES
Here are some simple examples of mu queries; you can make many more complicated queries using various logical operators, parentheses and so on, but in the author's experience, it's usually faster to find a message with a simple query just searching for some words.

Find all messages with both 'bee' and 'bird' (in any field)

```
bee AND bird
```

Find all messages with either Frodo or Sam:

```
Frodo OR Sam
```

Find all messages with the 'wombat' as subject, and 'capybara' anywhere:

```
subject:wombat and capybara
```

Find all messages in the 'Archive' folder from Fred:

```
from:fred and maildir:/Archive
```

Find all unread messages with attachments:

```
flag:attach and flag:unread
```

Find all messages with PDF-attachments:

```
mime:application/pdf
```

Find all messages with attached images:

```
mime:image/*
```

## CAVEATS
With current Xapian versions, the apostroph character is considered part of a word. Thus, you cannot find D'Artagnan by searching for Artagnan. So, include the apostroph in search or use a regexp search.

Matching on spaces has changed compared to the old query-parser; this applies e.g. to Maildirs that have spaces in their name, such as Sent Items. See MAILDIR above.

## REPORTING BUGS
Please report bugs at https://github.com/djcb/mu/issues.

## AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

## COPYRIGHT
This manpage is part of mu 1.10.7.

Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

## SEE ALSO
mu-find(1), mu-fields(1), *pcre(3)


munge

package: munge

title: munge(7)

summary: MUNGE overview

text:
# munge(7)

## NAME
munge - MUNGE overview

## INTRODUCTION
MUNGE (MUNGE Uid 'N' Gid Emporium) is an authentication service for creating and validating user credentials. It is designed to be highly scalable for use in an HPC cluster environment. It provides a portable API for encoding the user's identity into a tamper-proof credential that can be obtained by an untrusted client and forwarded by untrusted intermediaries within a security realm. Clients within this realm can create and validate credentials without the use of root privileges, reserved ports, or platform-specific methods.

## RATIONALE
The need for MUNGE arose out of the HPC cluster environment. Consider the scenario in which a local daemon running on a login node receives a client request and forwards it on to remote daemons running on compute nodes within the cluster. Since the user has already logged on to the login node, the local daemon just needs a reliable means of ascertaining the UID and GID of the client process. Furthermore, the remote daemons need a mechanism to ensure the forwarded authentication data has not been subsequently altered.

A common solution to this problem is to use Unix domain sockets to determine the identity of the local client, and then forward this information on to remote hosts via trusted rsh connections. But this presents several new problems. First, there is no portable API for determining the identity of a client over a Unix domain socket. Second, rsh connections must originate from a reserved port; the limited number of reserved ports available on a given host directly limits scalability. Third, root privileges are required in order to bind to a reserved port. Finally, the remote daemons have no means of determining whether the client identity is authentic. MUNGE solves all of these problems.

## USAGE
A process creates a credential by requesting one from the local MUNGE service, either via the munge_encode() C library call or the munge executable. The encoded credential contains the UID and GID of the originating process. This process sends the credential to another process within the security realm as a means of proving its identity. The receiving process validates the credential with the use of its local MUNGE service, either via the munge_decode() C library call or the unmunge executable. The decoded credential provides the receiving process with a reliable means of ascertaining the UID and GID of the originating process. This information can be used for accounting or access control decisions.

## DETAILS
The contents of the credential (including any optional payload data) are encrypted with a key shared by all munged daemons within the security realm. The integrity of the credential is ensured by a message authentication code (MAC). The credential is valid for a limited time defined by its time-to-live (TTL); this presumes clocks within a security realm are in sync. Unexpired credentials are tracked by the local munged daemon in order to prevent replay attacks on a given host. Decoding of a credential can be restricted to a particular user and/or group ID. The payload data can be used for purposes such as embedding the destination's address to ensure the credential is only valid on a specific host. The internal format of the credential is encoded in a platform-independent manner. And the credential itself is base64 encoded to allow it to be transmitted over virtually any transport.

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

## COPYRIGHT
Copyright (C) 2007-2022 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), munged(8), mungekey(8).

https://dun.github.io/munge/


netavark-firewalld

package: netavark

title: netavark-firewalld(7)

text:
# netavark-firewalld(7)

## Name
netavark-firewalld - description of the interaction of Netavark and firewalld

## Description
Netavark can be used on systems with firewalld enabled without issue. When using the default nftables or iptables firewall drivers, on systems where firewalld is running, firewalld will automatically be configured to allow connectivity to Podman containers. All subnets of Podman-managed networks will be automatically added to the trusted zone to allow this access.

### Firewalld Driver
There is also a dedicated firewalld driver in Netavark. This driver uses the firewalld DBus API to natively interact with firewalld. It can be enabled by setting firewall_driver to firewalld in containers.conf. The native firewalld driver offers better integration with firewalld, but presently suffers from several limitations. It does not support isolation (the --opt isolate= option to podman network create. Connections to ports forwarded by a container on the same host can only be made through the IPv4 localhost IP (127.0.0.1). Using other IPs on the host will not work, unless the connection comes from a separate host.

### Strict Port Forwarding
Since firewalld version 2.3.0, a new setting, StrictForwardPorts, has been added. The setting is located in /etc/firewalld/firewalld.conf and defaults to no (disabled). When disabled, port forwarding with Podman works as normal. When it is enabled (set to yes), port forwarding with root Podman will become nonfunctional. Attempting to start a container or pod with the -p or -P options will return errors. When StrictForwardPorts is enabled, all port forwarding must be done through firewalld using the firewall-cmd tool. This ensures that containers cannot allow traffic through the firewall without administrator intervention. Please note that rootless Podman is unaffected by this setting and will function as it always has.

Instead, containers should be started without forwarded ports specified and preferably with static IPs.

To forward a port externally, the following command should be run, substituting the desired host and container port numbers, protocol, and the container's IP.

```
# firewall-cmd --permanent --zone {ZONE} --add-forward-port=port={HOST_PORT_NUMBER}:proto={PROTOCOL}:toport={CONTAINER_PORT_NUMBER}:toaddr={CONTAINER_IP}
```

If you are not sure which zone to use, the public zone should always work.

If the container does not have a static IP, it can be found with podman inspect:

```
# podman inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' {CONTAINER_NAME_OR_ID}
```

Once the container is stopped or removed, the rule must be manually removed with the following command:

```
# firewall-cmd --permanent --zone {ZONE} --remove-forward-port=port={HOST_PORT_NUMBER}:proto={PROTOCOL}:toport={CONTAINER_PORT_NUMBER}:toaddr={CONTAINER_IP}
```

To also allow forwarding via IPv4 localhost (127.0.0.1), a firewalld policy must be added, as well as a rich rule for each port requiring localhost forwarding. Forwarding via IPv6 localhost is not possible due to kernel limitations.

To add the policies required for IPv4 localhost forwarding, the following commands must be run. This is only necessary once per system.

```
# firewall-cmd --permanent --new-policy localhostForward
# firewall-cmd --permanent --policy localhostForward --add-ingress-zone HOST
# firewall-cmd --permanent --policy localhostForward --add-egress-zone ANY
```

A further rich rule for each container is required:

```
# firewall-cmd --permanent --policy localhostForward --add-rich-rule='rule family=ipv4 destination address=127.0.0.0/8 forward-port port={HOST_PORT_NUMBER} protocol={PROTOCOL} to-port={CONTAINER_PORT_NUMBER} to-addr={CONTAINER_IP}'
```

These rules must be manually removed when the container is stopped or removed with the following command:

```
# firewall-cmd --permanent --policy localhostForward --remove-rich-rule='rule family=ipv4 destination address=127.0.0.0/8 forward-port port={HOST_PORT_NUMBER} protocol={PROTOCOL} to-port={CONTAINER_PORT_NUMBER} to-addr={CONTAINER_IP}'
```

The associated localhostForward policy does not need to be removed.

Please also note that, at present, it is only possible to access forwarded ports of a container on the same host via the IPv4 localhost IP (127.0.0.1), and only when the rich rule above has been applied. Accessing via an IP that is not 127.0.0.1 from the same host is presently not possible, but we hope to address this with a future firewalld release.

Please note that the firewalld driver presently bypasses this protection, and will still allow traffic through the firewall when StrictForwardPorts is enabled without manual forwarding through firewall-cmd. This may be changed in a future release.

## SEE ALSO
firewalld(1), firewall-cmd(1), firewalld.conf(5), podman(1), containers.conf(5)

## Authors
Matthew Heon ⟨mheon@redhat.com⟩


nfs.systemd

package: nfs-clients

title: nfs.systemd(7)

summary: managing NFS services through systemd.

text:
# nfs.systemd(7)

## NAME
nfs.systemd - managing NFS services through systemd.

## SYNOPSIS
nfs-utils.service

nfs-server.service

nfs-client.target

etc

## DESCRIPTION
The nfs-utils package provides a suite of systemd unit files which allow the various services to be started and managed. These unit files ensure that the services are started in the correct order, and the prerequisites are active before dependant services start. As there are quite few unit files, it is not immediately obvious how best to achieve certain results. The following subsections attempt to cover the issues that are most likely to come up.

### Configuration
The standard systemd unit files do not provide any easy way to pass any command line arguments to daemons so as to configure their behavior. In many case such configuration can be performed by making changes to /etc/nfs.conf or other configuration files (see nfs.conf(5)). When that is not convenient, a distribution might provide systemd "drop-in" files which replace the ExecStart= setting to start the program with different arguments. For example a drop-in file systemd/system/nfs-mountd.service.d/local.conf containing

```
[Service]
EnvironmentFile=/etc/sysconfig/nfs
ExecStart=
ExecStart= /usr/sbin/rpc.mountd $RPCMOUNTDOPTS
```

would cause the nfs-mountd.service unit to run the rpc.mountd program using, for arguments, the value given for RPCMOUNTDOPTS in /etc/sysconfig/nfs. This allows for seamless integration with existing configuration tools.

### Enabling unit files
There are three unit files which are designed to be manually enabled. All others are automatically run as required. The three are:

nfs-client.target

This should be enabled on any host which ever serves as an NFS client. There is little cost in transparently enabling it whenever NFS client software is installed.

nfs-server.service

This must be enabled to provide NFS service to clients. It starts and configures the required daemons in the required order.

nfs-blkmap.service

The blkmapd daemon is only required on NFS clients which are using pNFS (parallel NFS), and particularly using the blocklayout layout protocol. If you might use this particular extension to NFS, the nfs-blkmap.service unit should be enabled.

Several other units which might be considered to be optional, such as rpc-gssd.service are careful to only start if the required configuration file exists. rpc-gssd.service will not start if the krb5.keytab file does not exist (typically in /etc).

### Restarting NFS services
Most NFS daemons can be restarted at any time. They will reload any state that they need, and continue servicing requests. This is rarely necessary though.

When configuration changesare make, it can be hard to know exactly which services need to be restarted to ensure that the configuration takes effect. The simplest approach, which is often the best, is to restart everything. To help with this, the nfs-utils.service unit is provided. It declares appropriate dependencies with other unit files so that

systemctl restart nfs-utils

will restart all NFS daemons that are running. This will cause all configuration changes to take effect except for changes to mount options lists in /etc/fstab or /etc/nfsmount.conf. Mount options can only be changed by unmounting and remounting filesystem. This can be a disruptive operation so it should only be done when the value justifies the cost. The command umount -a -t nfs; mount -a -t nfs

should unmount and remount all NFS filesystems.

### Masking unwanted services
Rarely there may be a desire to prohibit some services from running even though there are normally part of a working NFS system. This may be needed to reduce system load to an absolute minimum, or to reduce attack surface by not running daemons that are not absolutely required.

Three particular services which this can apply to are rpcbind, idmapd, and rpc-gssd. rpcbind is not part of the nfs-utils package, but it used by several NFS services. However it is not needed when only NFSv4 is in use. If a site will never use NFSv3 (or NFSv2) and does not want rpcbind to be running, the correct approach is to run

systemctl mask rpcbind

This will disable rpcbind, and the various NFS services which depend on it (and are only needed for NFSv3) will refuse to start, without interfering with the operation of NFSv4 services. In particular, rpc.statd will not run when rpcbind is masked. idmapd is only needed for NFSv4, and even then is not needed when the client and server agree to use user-ids rather than user-names to identify the owners of files. If idmapd is not needed and not wanted, it can be masked with

systemctl mask idmapd

rpc-gssd is assumed to be needed if the krb5.keytab file is present. If a site needs this file present but does not want rpc-gssd running, it can be masked with systemctl mask rpc-gssd

## FILES
/etc/nfs.conf

/etc/nfsmount.conf

/etc/idmapd.conf

Also similar files in /usr/etc and in related conf.d drop-in directories.

## SEE ALSO
systemd.unit(5), nfs.conf(5), nfsmount.conf(5).


nfsd

package: nfs-server

title: nfsd(7)

text:
# nfsd(7)

## NAME
nfsd - special filesystem for controlling Linux NFS server

## SYNPOSIS
mount -t nfsd nfsd /proc/fs/nfsd

## DESCRIPTION
The nfsd filesystem is a special filesystem which provides access to the Linux NFS server. Writing to files in this filesystem can affect the server. Reading from them can provide information about the server.

As well as this filesystem, there are a collection of files in the procfs filesystem (normally mounted at /proc) which are used to control the NFS server. This manual page describes all of these files.

The exportfs and mountd programs (part of the nfs-utils package) expect to find this filesystem mounted at /proc/fs/nfsd or /proc/fs/nfs.

## DETAILS
Files in the nfsd filesystem include:

exports

This file contains a list of filesystems that are currently exported and clients that each filesystem is exported to, together with a list of export options for that client/filesystem pair. This is similar to the /proc/fs/nfs/exports file in 2.4. One difference is that a client doesn't necessarily correspond to just one host. It can respond to a large collection of hosts that are being treated identically. Each line of the file contains a path name, a client name, and a number of options in parentheses. Any space, tab, newline or back-slash character in the path name or client name will be replaced by a backslash followed by the octal ASCII code for that character.

threads

This file represents the number of nfsd thread currently running. Reading it will show the number of threads. Writing an ASCII decimal number will cause the number of threads to be changed (increased or decreased as necessary) to achieve that number.

filehandle

This is a somewhat unusual file in that what is read from it depends on what was just written to it. It provides a transactional interface where a program can open the file, write a request, and read a response. If two separate programs open, write, and read at the same time, their requests will not be mixed up. The request written to filehandle should be a client name, a path name, and a number of bytes. This should be followed by a newline, with white-space separating the fields, and octal quoting of special characters.

On writing this, the program will be able to read back a filehandle for that path as exported to the given client. The filehandle's length will be at most the number of bytes given.

The filehandle will be represented in hex with a leading '\x'.

clients/

This directory contains a subdirectory for each NFSv4 client. Each file under that subdirectory gives some details about the client in YAML format. In addition, writing "expire\n" to the ctl file will force the server to immediately revoke all state held by that client.

The directory /proc/net/rpc in the procfs filesystem contains a number of files and directories. The files contain statistics that can be display using the nfsstat program. The directories contain information about various caches that the NFS server maintains to keep track of access permissions that different clients have for different filesystems. The caches are:

auth.unix.ip

This cache contains a mapping from IP address to the name of the authentication domain that the ipaddress should be treated as part of.

nfsd.export

This cache contains a mapping from directory and domain to export options.

nfsd.fh

This cache contains a mapping from domain and a filesystem identifier to a directory. The filesystem identifier is stored in the filehandles and consists of a number indicating the type of identifier and a number of hex bytes indicating the content of the identifier.

Each directory representing a cache can hold from 1 to 3 files. They are:

flush

When a number of seconds since epoch (1 Jan 1970) is written to this file, all entries in the cache that were last updated before that file become invalidated and will be flushed out. Writing a time in the future (in seconds since epoch) will flush everything. This is the only file that will always be present.

content

This file, if present, contains a textual representation of ever entry in the cache, one per line. If an entry is still in the cache (because it is actively being used) but has expired or is otherwise invalid, it will be presented as a comment (with a leading hash character).

channel

This file, if present, acts a channel for request from the kernel-based nfs server to be passed to a user-space program for handling. When the kernel needs some information which isn't in the cache, it makes a line appear in the channel file giving the key for the information. A user-space program should read this, find the answer, and write a line containing the key, an expiry time, and the content. For example the kernel might make nfsd 127.0.0.1

appear in the auth.unix.ip/content file. The user-space program might then write nfsd 127.0.0.1 1057206953 localhost

to indicate that 127.0.0.1 should map to localhost, at least for now.

If the program uses select(2) or poll(2) to discover if it can read from the channel then it will never see and end-of-file but when all requests have been answered, it will block until another request appears.

In the /proc filesystem there are 4 files that can be used to enabled extra tracing of nfsd and related code. They are:

/proc/sys/sunrpc/nfs_debug

/proc/sys/sunrpc/nfsd_debug

/proc/sys/sunrpc/nlm_debug

/proc/sys/sunrpc/rpc_debug

They control tracing for the NFS client, the NFS server, the Network Lock Manager (lockd) and the underlying RPC layer respectively. Decimal numbers can be read from or written to these files. Each number represents a bit-pattern where bits that are set cause certain classes of tracing to be enabled. Consult the kernel header files to find out what number correspond to what tracing.

## NOTES
This file system is only available in Linux 2.6 and later series kernels (and in the later parts of the 2.5 development series leading up to 2.6). This man page does not apply to 2.4 and earlier.

Previously the nfsctl systemcall was used for communication between nfsd and user utilities. That systemcall was removed in kernel version 3.1. Older nfs-utils versions were able to fall back to nfsctl if necessary; that was removed from nfs-utils 1.3.5.

## SEE ALSO
nfsd(8), rpc.nfsd(8), exports(5), nfsstat(8), mountd(8) exportfs(8).

## AUTHOR
NeilBrown


notmuch-properties

package: notmuch

title: notmuch-properties(7)

text:
# notmuch-properties(7)

## NAME
notmuch-properties - notmuch message property conventions and documentation

## SYNOPSIS
notmuch count property:<key>=<value>

notmuch search property:<key>=<value>

notmuch show property:<key>=<value>

notmuch reindex property:<key>=<value>

notmuch tag +<tag> property:<key>=<value>

notmuch dump --include=properties

notmuch restore --include=properties

## DESCRIPTION
Several notmuch commands can search for, modify, add or remove properties associated with specific messages. Properties are key/value pairs, and a message can have more than one key/value pair for the same key.

While users can select based on a specific property in their search terms with the prefix property:, the notmuch command-line interface does not provide mechanisms for modifying properties directly to the user.

Instead, message properties are expected to be set and used programmatically, according to logic in notmuch itself, or in extensions to it.

Extensions to notmuch which make use of properties are encouraged to report the specific properties used to the upstream notmuch project, as a way of avoiding collisions in the property namespace.

## CONVENTIONS
Any property with a key that starts with "index." will be removed (and possibly re-set) upon reindexing (see notmuch-reindex(1)).

## MESSAGE PROPERTIES
The following properties are set by notmuch internally in the course of its normal activity.

index.decryption

If a message contains encrypted content, and notmuch tries to decrypt that content during indexing, it will add the property index.decryption=success when the cleartext was successfully indexed. If notmuch attempts to decrypt any part of a message during indexing and that decryption attempt fails, it will add the property index.decryption=failure to the message. Note that it's possible for a single message to have both index.decryption=success and index.decryption=failure. Consider an encrypted e-mail message that contains another encrypted e-mail message as an attachment -- if the outer message can be decrypted, but the attached part cannot, then both properties will be set on the message as a whole.

If notmuch never tried to decrypt an encrypted message during indexing (which is the default, see index.decrypt in notmuch-config(1)), then this property will not be set on that message.

session-key

When notmuch-show(1) or nomtuch-reply encounters a message with an encrypted part, if notmuch finds a session-key property associated with the message, it will try that stashed session key for decryption. If you do not want to use any stashed session keys that might be present, you should pass those programs --decrypt=false.

Using a stashed session key with "notmuch show" will speed up rendering of long encrypted threads. It also allows the user to destroy the secret part of any expired encryption-capable subkey while still being able to read any retained messages for which they have stashed the session key. This enables truly deletable e-mail, since (once the session key and asymmetric subkey are both destroyed) there are no keys left that can be used to decrypt any copy of the original message previously stored by an adversary.

However, access to the stashed session key for an encrypted message permits full byte-for-byte reconstruction of the cleartext message. This includes attachments, cryptographic signatures, and other material that cannot be reconstructed from the index alone.

See index.decrypt in notmuch-config(1) for more details about how to set notmuch's policy on when to store session keys.

The session key should be in the ASCII text form produced by GnuPG. For OpenPGP, that consists of a decimal representation of the hash algorithm used (identified by number from RFC 4880, e.g. 9 means AES-256) followed by a colon, followed by a hexadecimal representation of the algorithm-specific key. For example, an AES-128 key might be stashed in a notmuch property as: session-key=7:14B16AF65536C28AF209828DFE34C9E0.

index.repaired

Some messages arrive in forms that are confusing to view; they can be mangled by mail transport agents, or the sending mail user agent may structure them in a way that is confusing. If notmuch knows how to both detect and repair such a problematic message, it will do so during indexing. If it applies a message repair during indexing, it will use the index.repaired property to note the type of repair(s) it performed.

index.repaired=skip-protected-headers-legacy-display indicates that when indexing the cleartext of an encrypted message, notmuch skipped over a "legacy-display" text/rfc822-headers part that it found in that message, since it was able to index the built-in protected headers directly.

index.repaired=mixedup indicates the repair of a "Mixed Up" encrypted PGP/MIME message, a mangling typically produced by Microsoft's Exchange MTA. See https://tools.ietf.org/html/draft-dkg-openpgp-pgpmime-message-mangling for more information.

## SEE ALSO
notmuch(1), notmuch-config(1), notmuch-dump(1), notmuch-insert(1), notmuch-new(1), notmuch-reindex(1), notmuch-reply(1), notmuch-restore(1), notmuch-show(1), *notmuch-search-terms(7)

## AUTHOR
Carl Worth and many others

## COPYRIGHT
2009-2021, Carl Worth and many others


notmuch-search-terms

title: notmuch-search-terms(7)

summary: syntax for notmuch queries

text:
# notmuch-search-terms(7)

## NAME
notmuch-search-terms - syntax for notmuch queries

## SYNOPSIS
notmuch count [option ...] <search-term> ...

notmuch dump [--gzip] [--format=(batch-tag|sup)] [--output=<file>] [--] [<search-term> ...]

notmuch reindex [option ...] <search-term> ...

notmuch search [option ...] <search-term> ...

notmuch show [option ...] <search-term> ...

notmuch tag +<tag> ... -<tag> [--] <search-term> ...

## DESCRIPTION
Several notmuch commands accept a common syntax for search terms.

The search terms can consist of free-form text (and quoted phrases) which will match all messages that contain all of the given terms/phrases in the body, the subject, or any of the sender or recipient headers.

As a special case, a search string consisting of exactly a single asterisk ("*") will match all messages.

### Search prefixes
In addition to free text, the following prefixes can be used to force terms to match against specific portions of an email, (where <brackets> indicate user-supplied values).

Some of the prefixes with <regex> forms can be also used to restrict the results to those whose value matches a regular expression (see regex(7)) delimited with //, for example:

```
notmuch search 'from:"/bob@.*[.]example[.]com/"'
```

body:<word-or-quoted-phrase>

Match terms in the body of messages.

from:<name-or-address> or from:/<regex>/

The from: prefix is used to match the name or address of the sender of an email message.

to:<name-or-address>

The to: prefix is used to match the names or addresses of any recipient of an email message, (whether To, Cc, or Bcc).

subject:<word-or-quoted-phrase> or subject:/<regex>/

Any term prefixed with subject: will match only text from the subject of an email. Searching for a phrase in the subject is supported by including quotation marks around the phrase, immediately following subject:.

attachment:<word>

The attachment: prefix can be used to search for specific filenames (or extensions) of attachments to email messages.

mimetype:<word>

The mimetype: prefix will be used to match text from the content-types of MIME parts within email messages (as specified by the sender).

tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/

For tag: and is: valid tag values include inbox and unread by default for new messages added by notmuch new as well as any other tag values added manually with notmuch tag.

id:<message-id> or mid:<message-id> or mid:/<regex>/

For id: and mid:, message ID values are the literal contents of the Message-ID: header of email messages, but without the '<', '>' delimiters.

thread:<thread-id>

The thread: prefix can be used with the thread ID values that are generated internally by notmuch (and do not appear in email messages). These thread ID values can be seen in the first column of output from notmuch search

thread:{<notmuch query>}

Threads may be searched for indirectly by providing an arbitrary notmuch query in {}. For example, the following returns threads containing a message from mallory and one (not necessarily the same message) with Subject containing the word "crypto".

```
% notmuch search 'thread:"{from:mallory}" and thread:"{subject:crypto}"'
```

The performance of such queries can vary wildly. To understand this, the user should think of the query thread:{<something>} as expanding to all of the thread IDs which match <something>; notmuch then performs a second search using the expanded query.

path:<directory-path> or path:<directory-path>/** or path:/<regex>/

The path: prefix searches for email messages that are in particular directories within the mail store. The directory must be specified relative to the top-level maildir (and without the leading slash). By default, path: matches messages in the specified directory only. The "/**" suffix can be used to match messages in the specified directory and all its subdirectories recursively. path:"" matches messages in the root of the mail store and, likewise, path:** matches all messages. path: will find a message if any copy of that message is in the specific directory.

folder:<maildir-folder> or folder:/<regex>/

The folder: prefix searches for email messages by maildir or MH folder. For MH-style folders, this is equivalent to path:. For maildir, this includes messages in the "new" and "cur" subdirectories. The exact syntax for maildir folders depends on your mail configuration. For maildir++, folder:"" matches the inbox folder (which is the root in maildir++), other folder names always start with ".", and nested folders are separated by "."s, such as folder:.classes.topology. For "file system" maildir, the inbox is typically folder:INBOX and nested folders are separated by slashes, such as folder:classes/topology. folder: will find a message if any copy of that message is in the specific folder.

date:<since>..<until> or date:<date>

The date: prefix can be used to restrict the results to only messages within a particular time range (based on the Date: header). See DATE AND TIME SEARCH below for details on the range expression, and supported syntax for <since> and <until> date and time expressions.

The time range can also be specified using timestamps without including the date prefix using a syntax of:

<initial-timestamp>..<final-timestamp>

Each timestamp is a number representing the number of seconds since 1970-01-01 00:00:00 UTC. Specifying a time range this way is considered legacy and predates the date prefix.

lastmod:<initial-revision>..<final-revision>

The lastmod: prefix can be used to restrict the result by the database revision number of when messages were last modified (tags were added/removed or filenames changed). This is usually used in conjunction with the --uuid argument to notmuch search to find messages that have changed since an earlier query.

query:<name>

The query: prefix allows queries to refer to previously saved queries added with notmuch-config(1).

property:<key>=<value>

The property: prefix searches for messages with a particular <key>=<value> property pair. Properties are used internally by notmuch (and extensions) to add metadata to messages. A given key can be present on a given message with several different values. See notmuch-properties(7) for more details.

User defined prefixes are also supported, see notmuch-config(1) for details.

### Operators
In addition to individual terms, multiple terms can be combined with Boolean operators (and, or, not, and xor). Each term in the query will be implicitly connected by a logical AND if no explicit operator is provided (except that terms with a common prefix will be implicitly combined with OR). The shorthand '-<term>' can be used for 'not <term>' but unfortunately this does not work at the start of an expression. Parentheses can also be used to control the combination of the Boolean operators, but will have to be protected from interpretation by the shell, (such as by putting quotation marks around any parenthesized expression).

In addition to the standard boolean operators, Xapian provides several operators specific to text searching.

```
notmuch search term1 NEAR term2
```

will return results where term1 is within 10 words of term2. The threshold can be set like this:

```
notmuch search term1 NEAR/2 term2
```

The search

```
notmuch search term1 ADJ term2
```

will return results where term1 is within 10 words of term2, but in the same order as in the query. The threshold can be set the same as with NEAR:

```
notmuch search term1 ADJ/7 term2
```

### Stemming
Stemming in notmuch means that these searches

```
notmuch search detailed
notmuch search details
notmuch search detail
```

will all return identical results, because Xapian first "reduces" the term to the common stem (here 'detail') and then performs the search.

There are two ways to turn this off: a search for a capitalized word will be performed unstemmed, so that one can search for "John" and not get results for "Johnson"; phrase searches are also unstemmed (see below for details). Stemming is currently only supported for English. Searches for words in other languages will be performed unstemmed.

### Wildcards
It is possible to use a trailing '*' as a wildcard. A search for 'wildc*' will match 'wildcard', 'wildcat', etc.

### Boolean and Probabilistic Prefixes
Xapian (and hence notmuch) prefixes are either boolean, supporting exact matches like "tag:inbox" or probabilistic, supporting a more flexible term based searching. Certain special prefixes are processed by notmuch in a way not strictly fitting either of Xapian's built in styles. The prefixes currently supported by notmuch are as follows.

Boolean

tag:, id:, thread:, folder:, path:, property:

Probabilistic

body:, to:, attachment:, mimetype:

Special

from:, query:, subject:

### Terms and phrases
In general Xapian distinguishes between lists of terms and phrases. Phrases are indicated by double quotes (but beware you probably need to protect those from your shell) and insist that those unstemmed words occur in that order. One useful, but initially surprising feature is that the following are equivalent ways to write the same phrase.

- "a list of words"

- a-list-of-words

- a/list/of/words

- a.list.of.words

Both parenthesised lists of terms and quoted phrases are ok with probabilistic prefixes such as to:, from:, and subject:. In particular

```
subject:(pizza free)
```

is equivalent to

```
subject:pizza and subject:free
```

Both of these will match a subject "Free Delicious Pizza" while

```
subject:"pizza free"
```

will not.

### Quoting
Double quotes are also used by the notmuch query parser to protect boolean terms, regular expressions, or subqueries containing spaces or other special characters, e.g.

```
tag:"a tag"
```

```
folder:"/^.*/(Junk|Spam)$/"
```

```
thread:"{from:mallory and date:2009}"
```

As with phrases, you need to protect the double quotes from the shell e.g.

```
% notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
% notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
```

## DATE AND TIME SEARCH
notmuch understands a variety of standard and natural ways of expressing dates and times, both in absolute terms ("2012-10-24") and in relative terms ("yesterday"). Any number of relative terms can be combined ("1 hour 25 minutes") and an absolute date/time can be combined with relative terms to further adjust it. A non-exhaustive description of the syntax supported for absolute and relative terms is given below.

### The range expression
date:<since>..<until>

The above expression restricts the results to only messages from <since> to <until>, based on the Date: header.

<since> and <until> can describe imprecise times, such as "yesterday". In this case, <since> is taken as the earliest time it could describe (the beginning of yesterday) and <until> is taken as the latest time it could describe (the end of yesterday). Similarly, date:january..february matches from the beginning of January to the end of February.

If specifying a time range using timestamps in conjunction with the date prefix, each timestamp must be preceded by @ (ASCII hex 40). As above, each timestamp is a number representing the number of seconds since 1970-01-01 00:00:00 UTC. For example:

date:@<initial-timestamp>..@<final-timestamp>

Currently, spaces in range expressions are not supported. You can replace the spaces with '_', or (in most cases) '-', or (in some cases) leave the spaces out altogether. Examples in this man page use spaces for clarity.

Open-ended ranges are supported. I.e. it's possible to specify date:..<until> or date:<since>.. to not limit the start or end time, respectively.

### Single expression
date:<expr> works as a shorthand for date:<expr>..<expr>. For example, date:monday matches from the beginning of Monday until the end of Monday.

### Relative date and time
[N|number] (years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs) [...]

All refer to past, can be repeated and will be accumulated.

Units can be abbreviated to any length, with the otherwise ambiguous single m being m for minutes and M for months.

Number can also be written out one, two, ..., ten, dozen, hundred. Additionally, the unit may be preceded by "last" or "this" (e.g., "last week" or "this month").

When combined with absolute date and time, the relative date and time specification will be relative from the specified absolute date and time.

Examples: 5M2d, two weeks

### Supported absolute time formats

- H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]

- H[H] (am|a.m.|pm|p.m.)

- HHMMSS

- now

- noon

- midnight

- Examples: 17:05, 5pm

### Supported absolute date formats

- YYYY-MM[-DD]

- DD-MM[-[YY]YY]

- MM-YYYY

- M[M]/D[D][/[YY]YY]

- M[M]/YYYY

- D[D].M[M][.[YY]YY]

- D[D][(st|nd|rd|th)] Mon[thname] [YYYY]

- Mon[thname] D[D][(st|nd|rd|th)] [YYYY]

- Wee[kday]

Month names can be abbreviated at three or more characters.

Weekday names can be abbreviated at three or more characters.

Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3

### Time zones

- (+|-)HH:MM

- (+|-)HH[MM]

Some time zone codes, e.g. UTC, EET.

## SEE ALSO
notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1), notmuch-hooks(5), notmuch-insert(1), notmuch-new(1), notmuch-reindex(1), notmuch-properties(1), *notmuch-reply(1), notmuch-restore(1), notmuch-search(1), *notmuch-show(1), notmuch-tag(1)

## AUTHOR
Carl Worth and many others

## COPYRIGHT
2009-2021, Carl Worth and many others


nut

package: nut

title: nut(7)

summary: Overview of the Network UPS Tools (NUT)

text:
# nut(7)

## NAME
nut - Overview of the Network UPS Tools (NUT)

## DESCRIPTION
The Network UPS Tools (NUT) project provides a free and open source tool kit for monitoring and managing different types of power distribution devices, first released under such name in 1999 and following up from a few earlier projects. Since then, NUT has expanded to cover thousands of devices from hundreds of vendors, and to handle various device types (UPS, ePDU, ATS/STS, solar, blade server IPMI as a sort of PDU for the blades, etc.) all with a consistent API and data model, which has since been published as The "UPS management protocol", Informational RFC 9271.

While the project is in active development to support ever newer devices and their firmwares, as well as operating system releases, one of the internally recognized goals is to remain compatible with the systems NUT could have been once deployed on: even if vendors of those boxes and operating systems no longer exist, the venerable hardware deserves to be still protected with new UPS devices.

Although the original development involved POSIX-compliant operating systems, over time NUT for Windows support was also implemented (however as of NUT release v2.8.3, it remains not 100% complete) so it is possible to run the whole server and client stack as native Windows programs.

Most operating systems deliver NUT as packages built from a certain release, which for the project is just a better-tested snapshot of on-going development with an opinionated choice of build and run-time system configuration options. Some OS distribution maintainers pick fixes from later releases to update their software packages while nominally remaining on the same base line version that the corresponding major release of that distribution originally went with. This allows them to balance delivering stable programs with well-known qualities and minimal downsides for a long stretch of time that this OS release is supported (does not cause headaches during minor updates), but misses out on new capabilities, features (and yes, new bugs), which the on-going development regularly adds to the current code base du-jour.

As such, NUT community support for releases (or any other non-current code) is generally limited to suggestions based on experience, but any fixes happen on the main development branch (there are no release-tracking branches to port such solutions into), and custom builds of NUT would be required to apply them in an end-user environment. This workflow is highly automated in the project code base (its recipes and scripts), and the packaged dependencies or toolkits needed for a build are documented for numerous platforms (see links at the end of this page).

Thanks to this, the NUT project is also a wider open-source community leader and reference in the area of build recipes and testing automation for low-level multi-platform Autotools/C/C++ projects in general.

### NUT Architecture
The project follows a multi-tiered architecture which may seem a bit complex, but allows for flexibility with very different real-life setups to handle. In practice, this involves numerous programs (and their configuration files) running on the same or different systems (the "network" part in the name).

Many deployment scenarios are explored in the famous NUT Configuration Examples book maintained by Roger Price.

NUT Drivers

The lowest tier comprises NUT drivers, which are programs that can talk a particular protocol over certain media. Some protocols follow an industry standard (like USB HID or SNMP), or are dialects of a de-facto standard (like the originally Megatec "Q*" family of protocols used by many other vendors), but many others are vendor-specific. Some devices support several media connection types (e.g. Serial and/or USB ports, and/or SNMP for networked management), so there may be several suitable NUT drivers to choose from.

The NUT drivers are responsible for translation between NUT standard data point or instant command names and whatever strings need to be pulled for that particular device. The data is exposed to other programs on the same machine following the NUT Driver/Server Socket Protocol, which relies on operating system access controls for the UNIX local socket file or a Windows named pipe.

For each monitored power distribution device, a NUT driver instance should be running on a machine that has a communication link to that device.

Note There is currently no support for "multiplexing" information or commands for devices with multiple-media/multiple-driver access, e.g. to gain redundant connection or a better data collection than any one driver provides. For some devices it may be possible to run several drivers independently (probably for your monitoring system to cherry-pick data points from one driver or another), while others might only enable any one link exclusively.

NUT Data Server

A NUT Data Server (upsd(8)) represents one or more NUT drivers that run on the same machine as itself, to provide networked access to their data or pass around the instant command requests and replies.

On one side the data server connects to one or more UNIX local socket files or Windows named pipes (one for each running driver), and on another side it listens on the TCP/IP network (port 3493 by default) to communicate with local or remote client programs. It is also responsible for communication security for driver access, whether by defining the NUT user account names and assigned protocol access permissions (for value-setting or commands; read access is anonymous), or by handling the TLS/SSL part where enabled.

NUT Clients

Practical work visible to end-users is done by a multitude of NUT clients, many of which are delivered by the project itself and more are created and maintained by the community at large. Some standard clients of note include:

•upsmon(8) is a daemon to monitor primarily the states of UPSes (as opposed to other device types that NUT can handle) which power some power source units of this particular system, and based on how many PSUs are required for the system to run — initiates a local shutdown when too many UPSes are not in a healthy condition. Instances of this client allow a single UPS powering a whole rack or desk of computers to be seen by each of them (through a data server running on one of them, on a machine actually connected to the UPS — the "primary" system).

Note

The upsmon client typically splits into two processes: an unprivileged one running with credentials of its RUN_AS_USER configured in the upsmon.conf(5) file (or a built-in/packaged default like nut, ups, monuser or nobody) which does most of the work (including notification scripts called via NOTIFYCMD setting), and the part which remains owned by root to initiate the system shutdown by calling SHUTDOWNCMD when/if the time comes.

NUT deployments which desire higher-fidelity control (e.g. different systems shutting down after different time spent on battery) often couple the upsmon(8) with upssched(8) as their NOTIFYCMD handler. The upsmon primary system waits for secondary systems to disconnect as part of their shut down, and is usually also responsible for commanding the managed UPS to shut itself down and power up when the "wall power" returns (or to reset the load if it is already back), subject to UPS hardware capabilities. Most client integrations also stall the ultimate reboot/power-off of their machine, if its shut down was triggered by upsmon, and reboot after a long delay (if the machine is still alive). This combined approach allows to avoid the "power race condition", when systems would otherwise remain shut down indefinitely (until someone comes and reboots them) just because external power returned when the shut down spree had already started.

•upsc(8) is a command-line client for anonymous read-only access, used to list devices served by a NUT data server, or to query data points reported by a particular device.

•NUT-Monitor(8) is a GUI client for read-only or read-write access.

•A suite of CGI clients can run on a web server like Apache or nginx to provide a simple HTML interface to your devices.

Many monitoring systems integrate with NUT (and through it — with a varied assortment of power devices), using either simple clients like upsc or upslog, or libraries and bindings provided by the project itself (e.g. C, C++, Python, Java in a nearby repository) or by third-party efforts (e.g. Perl, Go, C#, REST API).

NUT Drivers during shutdown

Arguably another layer in this three-layer stack is a separate role for the NUT Driver programs on the upsmon(8) primary system as mentioned above: actually telling the UPS to turn off or power-cycle as part of your computer’s emergency shut down.

While the long-running services for the NUT drivers, data server and clients are stopped as part of common OS shutdown, there may be an "endgame" integration such as high-numbered SysV init scripts (e.g. /etc/rc0.d/K99nut) or the systemd shutdown hook facility, or even something built into the initrd or similar RAM disk image that originally launched the end-user visible OS and regains control when the OS says it is done. Please note that not all operating systems offer ways of such integration, and may resort to other solutions (perhaps calling such logic from the stop method of upsmon init script or service definition).

Either way, this integration has the effect of detecting that the currently processed shutdown is due to an upsmon FSD activity (e.g. that the flag file specified by POWERDOWNFLAG configuration option in upsmon.conf(5) exists and is valid), and launches the NUT driver program(s) again to connect to the UPS(es) that this system is a primary manager of (and has possibly out-of-band connections to), just to send them the requested command and exit.

For an example of such end-game integration please see the nutshutdown script if available in your packaged distribution, or its sources at https://github.com/networkupstools/nut/blob/master/scripts/systemd/nutshutdown.in which also implements a solution to avoid the "power race condition" (for operating systems that do not limit the duration of shutdown activity).

### NUT Run-time Nuances
For many more notes, please see the Frequently Asked Questions document in NUT sources or on the web site. A copy may be delivered by your packaging.

"File or directory not found" messages

When NUT daemon programs start, they check for existence of certain files they would create themselves (PID files, local sockets, etc.) and report when such file does not exist. Similarly, some programs try to signal an earlier instance (if the PID is known) and would report if that failed.

While this does look scary and confusing to people who use NUT for the first time and it greets them with what looks like error messages (we did work on improving the wording during the NUT v2.8.x release lineage due to frequent questions), these messages are in fact just a troubleshooting aspect that is useful at that point in program life cycle: if you expect "other" program instances to be running when they are not seen, this message helps catch the error:

•If this is a first run, so no artifacts from "another" instance of this program should be there, the message says just that.

•If your program starts and sees an older instance already running, further behavior depends on the situation (e.g. did you start a copy to signal the already running daemon with some command? did you start a new copy and so any old one is assumed stuck and should be terminated automatically?)

The "directory" part of the wording, which may be present in these messages, comes from the standard system library. It does not mean you should blindly create a directory (or any other object) for the file names listed in such reports.

That said, NUT does use directories (known in code and the configure script options as --with-pidpath, --with-altpidpath and --with-statepath) which should be created and assigned certain permissions each (the latter two may overlap). Generally this is done either by packaging, or by manual steps according to documentation when building NUT from sources. On some platforms (e.g. Linux with systemd and its systemd-tmpfiles subsystem) they may be maintained at run-time by configuration files delivered to the system.

The message can also be seen from upsmon(8) being unable to populate the POWERDOWNFLAG if the location it points to (/etc/killpower by default) does not exist or is read-only, or from a late shutdown integration script like the nutshutdown hook if that location was un-mounted by the time it runs. It is recommended to store that file on a volatile file system (under /var/run or /run on most modern distributions; typically the pidpath is located there too), which remains until reboot and disappears during reboot.

User/Group Accounts

Generally NUT daemon programs avoid running as a highly-privileged root account (on POSIX platforms), although they anticipate being started as such (most system services are) and drop privileges to run as the configured user and group accounts such as nut:nut.

•One notable exception is the upsmon(8) daemon which splits into a root-owned process which may trigger the OS shutdown routine, and an unprivileged process which does everything else.

•Default user and group accounts are built-in, selected as options for the configure script when it prepares the build of NUT. Those settings can be overridden by configuration file or command-line options of respective NUT daemons, whether to run as a different unprivileged user account (it may be possible to constrain each NUT service to run in their dedicated accounts), or to remain capable of everything as root (rarely, drivers are configured this way temporarily to troubleshoot local device access).

File system permissions

When using NUT drivers with local communications media (USB or Serial ports), you must ensure that the unprivileged run-time account like nut:nut is allowed access to those device file system nodes. On many platforms this can be automated with subsystems like udev, devd, hotplug, upower; on others (older ones) you may have to chmod/chown/chgrp particular devfs nodes (whether on the persistent filesystem, or using an init-script for volatile implementations).

Note that there are several run-time locations for data and socket files of NUT’s privileged and unprivileged programs, and for configuration files. Access to these directories and individual files should be secured according to NUT documentation. NUT daemons will warn about lax permissions in their syslog or console messages. Generally, root:nut and 0640 permissions are correct for most of the files (so the run-time NUT programs may only read them but can not rewrite them, not even if there happens to be an exploitable code problem discovered in them over time).

It is also important to note that (except for upslog(8)) no NUT daemons leave log files on their own: they send syslog messages, or write to stdout/stderr, and either or both of these streams can be saved to disk by the OS service integration (or a redirection from an init-script).

NUT Drivers as Service instances

Starting with NUT v2.8.0, on systems with service management frameworks (like Linux systemd or Solaris/illumos SMF) you may be even inadvertently using the nut-driver-enumerator(8) (also known as "NDE") facility. This is a script, which may be also called automatically (via packaging on supported platforms) at start-up or may be running continuously as a service, to process the ups.conf(5) file and maintain the service units (with their dependencies) for each driver section separately.

This sometimes raises eyebrows when end-users try to manually start a NUT driver program (either directly or using upsdrvctl(8) tool), and this either fails (because the device is already busy) or gets to conflict with the copy of the driver running as a service instance, and they begin to terminate each other.

Configuring NUT Drivers

To get started with the NUT server system, you should populate the ups.conf(5) file with a section per device, which informs both the respective drivers, and tools like service-aware upsdrvsvcctl(8) and nut-driver-enumerator(8) or the legacy upsdrvctl(8), and the upsd(8) data server, to name a few.

In many typical cases, the nut-scanner(8) tool can get you started by discovering supported USB, Serial, SNMP, NetXML, IPMI devices, or remote NUT deployments using Avahi mDNS or the good old port-knocking scan. This tool would propose a complete section content that you can copy-paste into your ups.conf file (possibly review and adapt the contents first, to e.g. add a description meaningful to you like "UPS in garage", etc.)

Other configuration files

NUT sample configuration files (packaged or seen in sources under https://github.com/networkupstools/nut/tree/master/conf directory) start with a heading comment about the minimal set of their required options. Note that many of these files can contain credentials (either for NUT roles, or for networked power devices as part of their NUT driver section configuration) and so these files and any of their backup copies should be secured accordingly.

The nut.conf(5) may be used by init-scripts or other system integration code (it notably contains the MODE setting to choose which profile of NUT services to start or not on this particular system).

On the NUT server you would need at least minimally configured: ups.conf(5), upsd.conf(5), upsd.users(5).

On the majority of NUT clients (meaning each system monitoring the UPS state so it knows when to trigger its local shutdown), you would need upsmon.conf(5) and depending on your setup, may need a custom NOTIFYCMD or SHUTDOWNCMD (if you script something complex), and/or upssched.conf(5) and a custom CMDSCRIPT for it.

For NUT CGI clients several files may need to be adapted and placed into certain directories according to their documentation: hosts.conf(5) and upsset.conf(5) for configuration, and upsstats-single.html and upsstats.html for HTML UI templates.

Other clients, whether delivered by NUT project (NUT-Monitor(8) GUI), or co-located (WMNut), or third-party (see https://networkupstools.org/projects.html), would probably support saving their settings or "favorites". Do not forget to secure access to those files and their copies as well.

## USER MANUAL PAGES

Note This build of NUT was configured to deliver only manual pages for programs that were actually built. For more information about the ecosystem please see the NUT website listing at https://networkupstools.org/docs/man/index.html or the sources of these pages at https://github.com/networkupstools/nut/tree/master/docs/man

### Configuration files
•nut.conf(5)

•ups.conf(5)

•upsd.conf(5)

•upsd.users(5)

•upsmon.conf(5)

•upssched.conf(5)

•hosts.conf(5)

•upsset.conf(5)

•upsstats.html(5)

### Daemons
•upsd(8)

•upsmon(8)

•upssched(8)

•upslog(8)

### Clients commands
•upsc(8)

•upscmd(8)

•upsrw(8)

•NUT-Monitor(8)

### Configuration commands
•nutconf(8)

•nut-scanner(8)

### CGI programs
•upsimage.cgi(8)

•upsset.cgi(8)

•upsstats.cgi(8)

### Platform management
Windows

•nut.exe(8)

### Driver control
•nut-driver-enumerator(8)

•upsdrvctl(8)

•upsdrvsvcctl(8)

### Drivers
•nutupsdrv(8)

•al175(8)

•apcsmart-old(8)

•apcsmart(8)

•apcupsd-ups(8)

•bcmxcp(8)

•bcmxcp_usb(8)

•belkin(8)

•belkinunv(8)

•bestfcom(8)

•bestfortress(8)

•bestuferrups(8)

•bestups(8)

•bicker_ser(8)

•blazer_ser(8)

•blazer_usb(8)

•clone-outlet(8)

•clone(8)

•dummy-ups(8)

•etapro(8)

•everups(8)

•failover(8)

•gamatronic(8)

•genericups(8)

•isbmex(8)

•ivtscd(8)

•liebert-esp2(8)

•liebert-gxe(8)

•liebert(8)

•masterguard(8)

•meanwell_ntu(8)

•metasys(8)

•mge-shut(8)

•mge-utalk(8)

•microdowell(8)

•microsol-apc(8)

•nhs_ser(8)

•nut-ipmipsu(8)

•nut-upower(8)

•nutdrv_atcl_usb(8)

•nutdrv_hashx(8)

•nutdrv_qx(8)

•nutdrv_siemens-sitop(8)

•oneac(8)

•optiups(8)

•powercom(8)

•powerpanel(8)

•powervar_cx_ser(8)

•powervar_cx_usb(8)

•rhino(8)

•richcomm_usb(8)

•riello_ser(8)

•riello_usb(8)

•safenet(8)

•sms_ser(8)

•snmp-ups(8)

•solis(8)

•tripplite(8)

•tripplite_usb(8)

•tripplitesu(8)

•upscode2(8)

•usbhid-ups(8)

•ve-direct(8)

•victronups(8)

## DEVELOPER MANUAL PAGES
•libupsclient-config(1)

•nut-recorder(8)

•skel(8)

•sockdebug(8)

### Client library
•libnutclient(3)

•libnutclient_commands(3)

•libnutclient_devices(3)

•libnutclient_general(3)

•libnutclient_misc(3)

•libnutclient_tcp(3)

•libnutclient_variables(3)

•upsclient(3)

•upscli_add_host_cert(3)

•upscli_cleanup(3)

•upscli_connect(3)

•upscli_tryconnect(3)

•upscli_disconnect(3)

•upscli_fd(3)

•upscli_get(3)

•upscli_init(3)

•upscli_set_default_connect_timeout(3)

•upscli_get_default_connect_timeout(3)

•upscli_init_default_connect_timeout(3)

•upscli_list_next(3)

•upscli_list_start(3)

•upscli_readline(3)

•upscli_sendline(3)

•upscli_splitaddr(3)

•upscli_splitname(3)

•upscli_ssl(3)

•upscli_strerror(3)

•upscli_upserror(3)

•upscli_str_add_unique_token(3)

•upscli_str_contains_token(3)

### Device discovery library
•nutscan(3)

•nutscan_add_device_to_device(3)

•nutscan_add_ip_range(3)

•nutscan_add_option_to_device(3)

•nutscan_cidr_to_ip(3)

•nutscan_display_parsable(3)

•nutscan_display_sanity_check(3)

•nutscan_display_sanity_check_serial(3)

•nutscan_display_ups_conf(3)

•nutscan_display_ups_conf_with_sanity_check(3)

•nutscan_free_device(3)

•nutscan_free_ip_ranges(3)

•nutscan_get_serial_ports_list(3)

•nutscan_init(3)

•nutscan_init_ip_ranges(3)

•nutscan_ip_ranges_iter_inc(3)

•nutscan_ip_ranges_iter_init(3)

•nutscan_new_device(3)

•nutscan_scan_avahi(3)

•nutscan_scan_eaton_serial(3)

•nutscan_scan_ipmi(3)

•nutscan_scan_nut(3)

•nutscan_scan_nut_simulation(3)

•nutscan_scan_snmp(3)

•nutscan_scan_usb(3)

•nutscan_scan_xml_http_range(3)

•nutscan_stringify_ip_ranges(3)

## INTERNET RESOURCES
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/ and specifically the NUT Documentation collection with the FAQ page and several books on different aspects of NUT usage and development, maintained as part of the project code base

•The NUT Configuration Examples book, maintained by Roger Price

•Project GitHub repository, wiki and issue tracker: https://github.com/networkupstools/nut

•Commonly referenced articles include:

•The NUT FAQ page

•Changing NUT daemon debug verbosity should be your first step in any troubleshooting

•Build prerequisites to make NUT from scratch on various Operating Systems documents the packages you might need to build NUT on about a dozen operating system distributions (most of those the NUT CI farm tests each development iteration on)

•Building NUT for in‐place upgrades or non‐disruptive tests details how to build a newer version of NUT than your system packaging provides (as a potential replacement of the older installation), e.g. to test if some issue got resolved or if an updated driver sees more information from your device; most such tests can be done without installing the new build into your system (not until you like it better than the current deployment)

•Specific bits of know-how and caveats regarding NUT for Windows

•Related projects

•We are on Wikipedia: https://en.wikipedia.org/wiki/Network_UPS_Tools

•The "UPS management protocol", Informational RFC 9271: https://datatracker.ietf.org/doc/html/rfc9271


title: o2cb(7)

text:
# o2cb(7)

## NAME
o2cb - Default cluster stack of the OCFS2 file system.

## SYNOPSIS
o2cb is the default cluster stack of the OCFS2 file system. It is an in-kernel cluster stack that includes a node manager (o2nm) to keep track of the nodes in the cluster, a disk heartbeat agent (o2hb) to detect node live-ness, a network agent (o2net) for intra-cluster node communication and a distributed lock manager (o2dlm) to keep track of lock resources. It also includes a synthetic file system, dlmfs, to allow applications to access the in-kernel dlm.

## CONFIGURATION
The stack is configured using the o2cb(8) cluster configuration utility and operated (online/offline/status) using the o2cb init service.

CLUSTER CONFIGURATION

It has two configuration files. One for the cluster layout (/etc/ocfs2/cluster.conf) and the other for the cluster timeouts, etc. (/etc/sysconfig/o2cb). More information about these two files can be found in ocfs2.cluster.conf(5) and o2cb.sysconfig(5).

The o2cb cluster stack supports two heartbeat modes, namely, local and global. Only one heartbeat mode can be active at any one time.

Local heartbeat refers to disk heartbeating on all shared devices. In this mode, the heartbeat is started during mount and stopped during umount. This mode is easy to setup as it does not require configuring heartbeat devices. The one drawback in this mode is the overhead on servers having a large number of OCFS2 mounts. For example, a server with 50 mounts will have 50 heartbeat threads. This is the default heartbeat mode.

Global heartbeat, on the other hand, refers to heartbeating on specific shared devices. These devices are normal OCFS2 formatted volumes that could also be mounted and used as clustered file systems. In this mode, the heartbeat is started during cluster online and stopped during cluster offline. While this mode can be used for all clusters, it is strongly recommended for clusters having a large number of mounts.

More information on disk heartbeat is provided below.

KERNEL CONFIGURATION

Two sysctl values need to be set for o2cb to function properly. The first, panic_on_oops, must be enabled to turn a kernel oops into a panic. If a kernel thread required for o2cb to function crashes, the system must be reset to prevent a cluster hang. If it is not set, another node may not be able to distinguish whether a node is unable to respond or slow to respond.

The other related sysctl parameter is panic, which specifies the number of seconds after a panic that the system will be auto-reset. Setting this parameter to zero disables autoreset; the cluster will require manual intervention. This is not preferred in a cluster environment.

To manually enable panic on oops and set a 30 sec timeout for reboot on panic, do:

```
# echo 1 > /proc/sys/kernel/panic_on_oops
# echo 30 > /proc/sys/kernel/panic

```

To enable the above on every boot, add the following to /etc/sysctl.conf:

```
kernel.panic_on_oops = 1
kernel.panic = 30

```

OS CONFIGURATION

The o2cb cluster stack also requires iptables (firewalling) to be either disabled or modified to allow network traffic on the private network interface. The port used by o2cb is specified in /etc/ocfs2/cluster.conf.

## DISK HEARTBEAT
O2CB uses disk heartbeat to detect node liveness. The disk heartbeat thread, o2hb, periodically reads and writes to a heartbeat file in a OCFS2 file system. Its write payload contains a sequence number that it increments in each write. This allows other nodes reading the same heartbeat file to detect the change and associate that with a live node. Conversely, a node whose sequence number has stopped changing is marked as a possible dead node. Possible. Not confirmed. That is because it just could be slow I/Os.

To differentiate between a dead node and one that has slow I/Os, O2CB has a disk heartbeat threshold (timeout). Only nodes whose sequence number has not incremented for that duration are marked dead.

However that node may not be dead but just experiencing slow I/O. To prevent that, the heartbeat thread keeps track of the time elapsed since the last completed write. If that time exceeds the timeout, it forces a self-fence. It does so to prevent other nodes from marking it as dead while it is still alive.

This self-fencing scheme has proven to be very reliable as it relies on kernel timers and pci bus reset. External fencing, while attractive, is rarely as reliable as it relies on external hardware and software that is prone to failure due to misconfiguration, etc.

Having said that, O2CB disk heartbeat has had its share of problems with self fencing. Nodes experiencing slow I/O on only one of multiple devices have to initiate self-fence.

This is because in the default local heartbeat scheme, nodes in a cluster may not be heartbeating on the same set of devices.

The global heartbeat mode addresses this shortcoming by introducing a scheme that forces all nodes to heartbeat on the same set of devices. In this scheme, a node experiencing a slowdown in I/O on a device may not need to initiate self-fence. It will only have to do so if it encounters slowdown on 50% or more of the heartbeat devices. In a cluster with 3 heartbeat regions, a slowdown in 1 region will be tolerated. In a cluster with 5 regions, a slowdown in 2 will be tolerated.

It is for this reason, this mode is recommended for users that have 3 or more OCFS2 mounts.

O2CB allows up to 32 heartbeat regions to be configured in the global heartbeat mode.

## ONLINE CLUSTER MODIFICATION
The O2CB cluster stack allows adding and removing nodes in an online cluster when run in the global heartbeat mode. Use the o2cb(8) utility to make the changes in the configuration and (re)online the cluster using the o2cb init script. The user must do the same on all nodes in the cluster. The cluster will not allow any new cluster mounts if the node configuration on all nodes is not the same.

The removal of nodes will only succeed if that node is no longer in use. If the user removes an active node from the configuration, the re-online will fail.

The cluster stack also allows adding and removing heartbeat regions in an online cluster. Use the o2cb(8) utility to make the changes in the configuration file and (re)online the cluster using the o2cb init script. The user must do the same on all nodes in the cluster. The cluster will not allow any new cluster mounts if the heartbeat region configuration on all nodes is not the same.

The removal of heartbeat regions will only succeed if the active heartbeat region count is greater than 3. This is to protect against edge conditions that can destabilize the cluster.

## GETTING STARTED
The first step in configuring o2cb is deciding whether to setup local or global heartbeat. If global heartbeat, then one has to format atleast one heartbeat device.

To format a OCFS2 volume with global heartbeat enabled, do:

```
# mkfs.ocfs2 --cluster-stack=o2cb --cluster-name=webcluster --global-heartbeat -L "hbvol1" /dev/sdb1
```

Once formatted, setup /etc/ocfs2/cluster.conf following the example provided in ocfs2.cluster.conf(5).

If local heartbeat, then one can setup cluster.conf without any heartbeat devices. The next step is starting the cluster.

To online the cluster stack, do:

```
# service o2cb online
Loading stack plugin "o2cb": OK
Loading filesystem "ocfs2_dlmfs": OK
Mounting ocfs2_dlmfs filesystem at /dlm: OK
Setting cluster stack "o2cb": OK
Registering O2CB cluster "webcluster": OK
Setting O2CB cluster timeouts : OK
Starting global heartbeat for cluster "webcluster": OK
```

Once the cluster stack is online, new OCFS2 volumes can be formatted normally without specifying the cluster stack information. mkfs.ocfs2(8) will pick up that information automatically.

```
# mkfs.ocfs2 -L "datavol" /dev/sdc1
```

Meanwhile existing volumes can be converted to the new cluster stack using tunefs.ocfs2(8) utility.

```
# tunefs.ocfs2 --update-cluster-stack /dev/sdd1
Updating on-disk cluster information to match the running cluster.
DANGER: YOU MUST BE ABSOLUTELY SURE THAT NO OTHER NODE IS USING THIS FILESYSTEM
BEFORE MODIFYING ITS CLUSTER CONFIGURATION.
Update the on-disk cluster information? y
```

Another utility mounted.ocfs2(8) is useful is listing all the OCFS2 volumes alonghwith the cluster stack information.

To get a list of OCFS2 volumes, do:

```
# mounted.ocfs2 -d
Device     Stack  Cluster     F  UUID                              Label
/dev/sdb1  o2cb   webcluster  G  DCDA2845177F4D59A0F2DCD8DE507CC3  hbvol1
/dev/sdc1  None                  23878C320CF3478095D1318CB5C99EED  localmount
/dev/sdd1  o2cb   webcluster  G  8AB016CD59FC4327A2CDAB69F08518E3  webvol
/dev/sdg1  o2cb   webcluster  G  77D95EF51C0149D2823674FCC162CF8B  logsvol
/dev/sdh1  o2cb   webcluster  G  BBA1DBD0F73F449384CE75197D9B7098  scratch
```

The o2cb init script can also be used to check the status of the cluster, offline the cluster, etc.

To check the status of the cluster stack, do:

```
# service o2cb status
Driver for "configfs": Loaded
Filesystem "configfs": Mounted
Stack glue driver: Loaded
Stack plugin "o2cb": Loaded
Driver for "ocfs2_dlmfs": Loaded
Filesystem "ocfs2_dlmfs": Mounted
Checking O2CB cluster "webcluster": Online

  Heartbeat dead threshold: 62

  Network idle timeout: 60000

  Network keepalive delay: 2000

  Network reconnect delay: 2000

  Heartbeat mode: Global
Checking O2CB heartbeat: Active

  77D95EF51C0149D2823674FCC162CF8B /dev/sdg1

  DCDA2845177F4D59A0F2DCD8DE507CC3 /dev/sdk1

  BBA1DBD0F73F449384CE75197D9B7098 /dev/sdh1
Nodes in O2CB cluster: 6 7 10
Active userdlm domains:  ovm
```

To offline and unload the cluster stack, do:

```
# service o2cb offline
Clean userdlm domains: OK
Stopping global heartbeat on cluster "webcluster": OK
Stopping O2CB cluster webcluster: OK
Unregistering O2CB cluster "webcluster": OK
# service o2cb unload
Clean userdlm domains: OK
Unmounting ocfs2_dlmfs filesystem: OK
Unloading module "ocfs2_dlmfs": OK
Unloading module "ocfs2_stack_o2cb": OK
```

## SEE ALSO
o2cb(8) o2cb.sysconfig(5) ocfs2.cluster.conf(5) o2hbmonitor(8)

## AUTHORS
Oracle Corporation

## COPYRIGHT
Copyright © 2004, 2011 Oracle. All rights reserved.