mu-query

package: mu

title: mu-query(7)

summary: a language for finding messages in mu

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.

NOTE: t 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 'banana' or 'hello', or words prefixed with a field-name which make them apply to just that field. See mufind 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 regular expressions that follow ECMAScript; for details, see

http://www.cplusplus.com/reference/regex/ECMAScript/

Regular expressions must be enclosed in //. Some examples:

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

```

```

Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the latter 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:. Here is the full table, a shortcut character and a description.

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

```

```

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 readabilty.

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, '2015' would be interpreted as the start of that year; as an upper bound as the 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..
e: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 FIELDS
The flag/g field allows you to match message flags. The following fields are available:

```
	d,draft         Draft Message
	f,flagged       Flagged
	n,new           New message (in new/ Maildir)
	p,passed        Passed ('Handled')
	r,replied       Replied
	s,seen          Seen
	t,trashed       Marked for deletion
	a,attach        Has attachment
	z,signed        Signed message
	x,encrypted     Encrypted message
	l,list          Mailing-list 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 'capibara' anywhere:

```
subject:wombat and capibara
```

```

```

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.

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

## SEE ALSO
mu-find(1)


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. 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

## 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


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.