title: idmap_ldap(8)

summary: Samba\*(Aqs idmap_ldap Backend for Winbind

text:
# idmap_ldap(8)

## NAME
idmap_ldap - Samba's idmap_ldap Backend for Winbind

## DESCRIPTION
The idmap_ldap plugin provides a means for Winbind to store and retrieve SID/uid/gid mapping tables in an LDAP directory service.

In contrast to read only backends like idmap_rid, it is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings.

## IDMAP OPTIONS
ldap_base_dn = DN

Defines the directory base suffix to use for SID/uid/gid mapping entries. If not defined, idmap_ldap will default to using the "ldap idmap suffix" option from /etc/samba/smb.conf.

ldap_user_dn = DN

Defines the user DN to be used for authentication. The secret for authenticating this user should be stored with net idmap secret (see net(8)). If absent, the ldap credentials from the ldap passdb configuration are used, and if these are also absent, an anonymous bind will be performed as last fallback.

ldap_url = ldap://server/

Specifies the LDAP server to use for SID/uid/gid map entries. If not defined, idmap_ldap will assume that ldap://localhost/ should be used.

range = low - high

Defines the available matching uid and gid range for which the backend is authoritative.

## EXAMPLES
The following example shows how an ldap directory is used as the default idmap backend. It also configures the idmap range and base directory suffix. The secret for the ldap_user_dn has to be set with "net idmap secret '*' password".

```
	[global]
	idmap config * : backend      = ldap
	idmap config * : range        = 1000000-1999999
	idmap config * : ldap_url     = ldap://localhost/
	idmap config * : ldap_base_dn = ou=idmap,dc=example,dc=com
	idmap config * : ldap_user_dn = cn=idmap_admin,dc=example,dc=com

```

This example shows how ldap can be used as a readonly backend while tdb is the default backend used to store the mappings. It adds an explicit configuration for some domain DOM1, that uses the ldap idmap backend. Note that a range disjoint from the default range is used.

```
	[global]
	# "backend = tdb" is redundant here since it is the default
	idmap config * : backend = tdb
	idmap config * : range = 1000000-1999999
	idmap config DOM1 : backend = ldap
	idmap config DOM1 : range = 2000000-2999999
	idmap config DOM1 : read only = yes
	idmap config DOM1 : ldap_url = ldap://server/
	idmap config DOM1 : ldap_base_dn = ou=idmap,dc=dom1,dc=example,dc=com
	idmap config DOM1 : ldap_user_dn = cn=idmap_admin,dc=dom1,dc=example,dc=com

```

## NOTE
In order to use authentication against ldap servers you may need to provide a DN and a password. To avoid exposing the password in plain text in the configuration file we store it into a security store. The "net idmap " command is used to store a secret for the DN specified in a specific idmap domain.

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


package: samba-winbind-common

title: idmap_nss(8)

summary: Samba\*(Aqs idmap_nss Backend for Winbind

text:
# idmap_nss(8)

## NAME
idmap_nss - Samba's idmap_nss Backend for Winbind

## DESCRIPTION
The idmap_nss plugin provides a means to map Unix users and groups to Windows accounts. This provides a simple means of ensuring that the SID for a Unix user named jsmith is reported as the one assigned to DOMAIN\jsmith which is necessary for reporting ACLs on files and printers stored on a Samba member server.

## IDMAP OPTIONS
range = low - high

Defines the available matching UID and GID range for which the backend is authoritative. Note that the range acts as a filter. Returned UIDs or GIDs by NSS modules that fall outside the range are ignored and the corresponding maps discarded. It is intended as a way to avoid accidental UID/GID overlaps between local and remotely defined IDs.

use_upn = <yes | no>

Some NSS modules can return and handle UPNs and/or down-level logon names (e.g., DOMAIN\user or user@REALM). If this parameter is enabled the returned names from NSS will be parsed and the resulting namespace will be used as the authoritative namespace instead of the IDMAP domain name. Also, down-level logon names will be sent to NSS instead of the plain username to give NSS modules a hint about the user's correct domain.

Default: no

## EXAMPLES
This example shows how to use idmap_nss to obtain the local account ID's for its own domain (SAMBA) from NSS, whilst allocating new mappings for the default domain (*) and any trusted domains.

```
	[global]
	idmap config * : backend = tdb
	idmap config * : range = 1000000-1999999
	idmap config SAMBA : backend  = nss
	idmap config SAMBA : range = 1000-999999

```

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


title: idmap_rfc2307(8)

summary: Samba\*(Aqs idmap_rfc2307 Backend for Winbind

text:
# idmap_rfc2307(8)

## NAME
idmap_rfc2307 - Samba's idmap_rfc2307 Backend for Winbind

## DESCRIPTION
The idmap_rfc2307 plugin provides a way for winbind to read id mappings from records in an LDAP server as defined in RFC 2307. The LDAP server can be stand-alone or the LDAP server provided by the AD server. An AD server is always required to provide the mapping between name and SID, and the LDAP server is queried for the mapping between name and uid/gid. This module implements only the "idmap" API, and is READONLY.

Mappings must be provided in advance by the administrator by creating the user accounts in the Active Directory server and the posixAccount and posixGroup objects in the LDAP server. The names in the Active Directory server and in the LDAP server have to be the same.

This id mapping approach allows the reuse of existing LDAP authentication servers that store records in the RFC 2307 format.

When connecting to the LDAP server provided by an AD server, the parameter ldap ssl ads determines whether SSL should be used. When using a stand-alone LDAP server, ldap ssl applies.

## IDMAP OPTIONS
range = low - high

Defines the available matching UID and GID range for which the backend is authoritative. Note that the range acts as a filter. If specified any UID or GID stored in AD that fall outside the range is ignored and the corresponding map is discarded. It is intended as a way to avoid accidental UID/GID overlaps between local and remotely defined IDs.

ldap_server = <ad | stand-alone >

Defines the type of LDAP server to use. This can either be the LDAP server provided by the Active Directory server (ad) or a stand-alone LDAP server.

bind_path_user

Specifies the search base where user objects can be found in the LDAP server.

bind_path_group

Specifies the search base where group objects can be found in the LDAP server.

user_cn = <yes | no>

Query cn attribute instead of uid attribute for the user name in LDAP. This option is not required, the default is no.

realm

Append @realm to cn for groups (and users if user_cn is set) in LDAP queries. This option is not required, the default is not to append the realm.

ldap_domain

When using the LDAP server in the Active Directory server, this allows one to specify the domain where to access the Active Directory server. This allows using trust relationships while keeping all RFC 2307 records in one place. This parameter is optional, the default is to access the AD server in the current domain to query LDAP records.

ldap_url

When using a stand-alone LDAP server, this parameter specifies the ldap URL for accessing the LDAP server.

ldap_user_dn

Defines the user DN to be used for authentication. The secret for authenticating this user should be stored with net idmap secret (see net(8)). If absent, an anonymous bind will be performed.

## EXAMPLES
The following example shows how to retrieve id mappings from a stand-alone LDAP server. This example also shows how to leave a small non conflicting range for local id allocation that may be used in internal backends like BUILTIN.

```
	[global]
	idmap config * : backend = tdb
	idmap config * : range = 1000000-1999999
	idmap config DOMAIN : backend = rfc2307
	idmap config DOMAIN : range = 2000000-2999999
	idmap config DOMAIN : ldap_server = stand-alone
	idmap config DOMAIN : ldap_url = ldap://ldap1.example.com
	idmap config DOMAIN : ldap_user_dn = cn=ldapmanager,dc=example,dc=com
	idmap config DOMAIN : bind_path_user = ou=People,dc=example,dc=com
	idmap config DOMAIN : bind_path_group = ou=Group,dc=example,dc=com

```

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


title: idmap_rid(8)

summary: Samba\*(Aqs idmap_rid Backend for Winbind

text:
# idmap_rid(8)

## NAME
idmap_rid - Samba's idmap_rid Backend for Winbind

## DESCRIPTION
The idmap_rid backend provides a way to use an algorithmic mapping scheme to map UIDs/GIDs and SIDs. No database is required in this case as the mapping is deterministic.

Currently, there should to be an explicit idmap configuration for each domain that should use the idmap_rid backend, using disjoint ranges.

NOTE: The idmap_rid backend can NOT be used as the default backend. One usually needs to define a writeable default idmap range, using a backend like tdb or ldap that can create unix ids, in order to be able to map the BUILTIN sids and other domains, and also in order to be able to create group mappings. See the example below.

## IDMAP OPTIONS
range = low - high

Defines the available matching uid and gid range for which the backend is authoritative. Note that the range acts as a filter. If algorithmically determined UID or GID fall outside the range, they are ignored and the corresponding map is discarded. It is intended as a way to avoid accidental UID/GID overlaps between local and remotely defined IDs.

base_rid = INTEGER

Defines the base integer used to build SIDs out of a UID or a GID, and to rebase the UID or GID to be obtained from a SID. This means SIDs with a RID less than the base rid are filtered. The default is not to restrict the allowed rids at all, i.e. a base_rid value of 0. Use of this parameter is deprecated.

## THE MAPPING FORMULAS
The Unix ID for a RID is calculated this way:

```
			ID = RID - BASE_RID + LOW_RANGE_ID.

```

Correspondingly, the formula for calculating the RID for a given Unix ID is this:

```
			RID = ID + BASE_RID - LOW_RANGE_ID.

```

## EXAMPLES
This example shows how to configure two domains with idmap_rid, the principal domain and a trusted domain, leaving the default id mapping scheme at tdb. The example also demonstrates the use of the base_rid parameter for the trusted domain.

```
	[global]
	security = domain
	workgroup = MAIN
	idmap config * : backend        = tdb
	idmap config * : range          = 1000000-1999999
	idmap config MAIN : backend     = rid
	idmap config MAIN : range       = 10000 - 49999
	idmap config TRUSTED : backend  = rid
	idmap config TRUSTED : range    = 50000 - 99999
	idmap config TRUSTED : base_rid = 500000

```

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


title: idmap_script(8)

summary: Samba\*(Aqs idmap_script Backend for Winbind

text:
# idmap_script(8)

## NAME
idmap_script - Samba's idmap_script Backend for Winbind

## DESCRIPTION
The idmap_script plugin is a substitute for the idmap_tdb2 backend used by winbindd for storing SID/uid/gid mapping tables in clustered environments with Samba and CTDB. It is a read only backend that uses a script to perform mapping.

It was developed out of the idmap_tdb2 back end and does not store SID/uid/gid mappings in a TDB, since the winbind_cache tdb will store the mappings once they are provided.

## IDMAP OPTIONS
range = low - high

Defines the available matching uid and gid range for which the backend is authoritative.

script

This option can be used to configure an external program for performing id mappings.

## IDMAP SCRIPT
The script idmap backend supports an external program for performing id mappings through the /etc/samba/smb.conf option idmap config * : script or its deprecated legacy form idmap : script.

The script should accept the following command line options.

```
	SIDTOID S-1-xxxx
	IDTOSID UID xxxx
	IDTOSID GID xxxx
	IDTOSID XID xxxx

```

And it should return one of the following responses as a single line of text.

```
	UID:yyyy
	GID:yyyy
	XID:yyyy
	SID:ssss
	ERR:yyyy

```

XID indicates that the ID returned should be both a UID and a GID. That is, it requests an ID_TYPE_BOTH, but it is ultimately up to the script whether or not it can honor that request. It can choose to return a UID or a GID mapping only.

## EXAMPLES
This example shows how script is used as the default idmap backend using an external program via the script parameter:

```
	[global]
	idmap config * : backend = script
	idmap config * : range = 1000000-2000000
	idmap config * : script = /usr/local/samba/bin/idmap_script.sh

```

This shows a simple script to partially perform the task:

```
	#!/bin/sh
	#
	# Uncomment this if you want some logging
	#echo $@ >> /tmp/idmap.sh.log
	if [ "$1" == "SIDTOID" ]
	then
		# Note. The number returned has to be within the range defined
		#echo "Sending UID:1000005" >> /tmp/idmap.sh.log
		echo "UID:1000005"
		exit 0
	else
		#echo "Sending ERR: No idea what to do" >> /tmp/idmap.sh.log
		echo "ERR: No idea what to do"
		exit 1
	fi

```

Clearly, this script is not enough, as it should probably use wbinfo to determine if an incoming SID is a user or group SID and then look up the mapping in a table or use some other mechanism for mapping SIDs to UIDs and etc.

Please be aware that the script is called with the _NO_WINBINDD environment variable set to 1. This prevents recursive calls into winbind from the script both via explicit calls to wbinfo and via implicit calls via nss_winbind. For example a call to ls -l could trigger such an infinite recursion.

It is safe to call wbinfo -n and wbinfo -s from within an idmap script. To do so, the script must unset the _NO_WINBINDD environment variable right before the call to wbinfo and set it to 1 again right after wbinfo has returned to protect against the recursion.

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


title: idmap_tdb(8)

summary: Samba\*(Aqs idmap_tdb Backend for Winbind

text:
# idmap_tdb(8)

## NAME
idmap_tdb - Samba's idmap_tdb Backend for Winbind

## DESCRIPTION
The idmap_tdb plugin is the default backend used by winbindd for storing SID/uid/gid mapping tables.

In contrast to read only backends like idmap_rid, it is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings.

## IDMAP OPTIONS
range = low - high

Defines the available matching uid and gid range for which the backend is authoritative.

## EXAMPLES
This example shows how tdb is used as the default idmap backend. This configured range is used for uid and gid allocation.

```
	[global]
	# "backend = tdb" is redundant here since it is the default
	idmap config * : backend = tdb
	idmap config * : range = 1000000-2000000

```

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


title: idmap_tdb2(8)

summary: Samba\*(Aqs idmap_tdb2 Backend for Winbind

text:
# idmap_tdb2(8)

## NAME
idmap_tdb2 - Samba's idmap_tdb2 Backend for Winbind

## DESCRIPTION
The idmap_tdb2 plugin is a substitute for the default idmap_tdb backend used by winbindd for storing SID/uid/gid mapping tables in clustered environments with Samba and CTDB.

In contrast to read only backends like idmap_rid, it is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings.

## IDMAP OPTIONS
range = low - high

Defines the available matching uid and gid range for which the backend is authoritative.

script

This option can be used to configure an external program for performing id mappings instead of using the tdb counter. The mappings are then stored int tdb2 idmap database. For details see the section on IDMAP SCRIPT below.

## IDMAP SCRIPT
The tdb2 idmap backend supports an external program for performing id mappings through the smb.conf option idmap config * : script or its deprecated legacy form idmap : script.

The mappings obtained by the script are then stored in the idmap tdb2 database instead of mappings created by the incrementing id counters. It is therefore important that the script covers the complete range of SIDs that can be passed in for SID to Unix ID mapping, since otherwise SIDs unmapped by the script might get mapped to IDs that had previously been mapped by the script.

The script should accept the following command line options.

```
	SIDTOID S-1-xxxx
	IDTOSID UID xxxx
	IDTOSID GID xxxx

```

And it should return one of the following responses as a single line of text.

```
	UID:yyyy
	GID:yyyy
	SID:yyyy
	ERR:yyyy

```

## EXAMPLES
This example shows how tdb2 is used as the default idmap backend.

```
	[global]
	idmap config * : backend = tdb2
	idmap config * : range = 1000000-2000000

```

This example shows how tdb2 is used as the default idmap backend using an external program via the script parameter:

```
	[global]
	idmap config * : backend = tdb2
	idmap config * : range = 1000000-2000000
	idmap config * : script = /usr/local/samba/bin/idmap_script.sh

```

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.


winbindd

title: winbindd(8)

text:
# winbindd(8)

## NAME
winbindd - Name Service Switch daemon for resolving names from NT servers

## SYNOPSIS
winbindd [-D|--daemon] [-i|--interactive] [-F|--foreground] [--no-process-group] [-n|--no-caching] [-d <debug level>] [--debug-stdout] [--configfile=<configuration file>] [--option=<name>=<value>] [-l|--log-basename <log directory>] [--leak-report] [--leak-report-full] [-V|--version]

## DESCRIPTION
This program is part of the samba(7) suite.

winbindd is a daemon that provides a number of services to the Name Service Switch capability found in most modern C libraries, to arbitrary applications via PAM and ntlm_auth and to Samba itself.

Even if winbind is not used for nsswitch, it still provides a service to smbd, ntlm_auth and the pam_winbind.so PAM module, by managing connections to domain controllers. In this configuration the idmap config * : range parameter is not required. (This is known as `netlogon proxy only mode'.)

The Name Service Switch allows user and system information to be obtained from different databases services such as NIS or DNS. The exact behaviour can be configured through the /etc/nsswitch.conf file. Users and groups are allocated as they are resolved to a range of user and group ids specified by the administrator of the Samba system.

The service provided by winbindd is called `winbind' and can be used to resolve user and group information from a Windows NT server. The service can also provide authentication services via an associated PAM module.

The pam_winbind module supports the auth, account and password module-types. It should be noted that the account module simply performs a getpwnam() to verify that the system can obtain a uid for the user, as the domain controller has already performed access control. If the libnss_winbind library has been correctly installed, or an alternate source of names configured, this should always succeed.

The following nsswitch databases are implemented by the winbindd service:

hosts

This feature is only available on IRIX. User information traditionally stored in the hosts(5) file and used by gethostbyname(3) functions. Names are resolved through the WINS server or by broadcast.

passwd

User information traditionally stored in the passwd(5) file and used by getpwent(3) functions.

group

Group information traditionally stored in the group(5) file and used by getgrent(3) functions.

For example, the following simple configuration in the /etc/nsswitch.conf file can be used to initially resolve user and group information from /etc/passwd and /etc/group and then from the Windows NT server.

```
passwd:         files winbind
group:          files winbind
## only available on IRIX: use winbind to resolve hosts:
# hosts:        files dns winbind
## All other NSS enabled systems should use libnss_wins.so like this:
hosts:          files dns wins
```

The following simple configuration in the /etc/nsswitch.conf file can be used to initially resolve hostnames from /etc/hosts and then from the WINS server.

```
hosts:		files wins
```

## OPTIONS
-D|--daemon

If specified, this parameter causes the server to operate as a daemon. That is, it detaches itself and runs in the background on the appropriate port. This switch is assumed if winbindd is executed on the command line of a shell.

-i|--interactive

Tells winbindd to not become a daemon and detach from the current terminal. This option is used by developers when interactive debugging of winbindd is required. winbindd also logs to standard output, as if the -S parameter had been given.

-F|--foreground

If specified, this parameter causes the main winbindd process to not daemonize, i.e. double-fork and disassociate with the terminal. Child processes are still created as normal to service each connection request, but the main process does not exit. This operation mode is suitable for running winbindd under process supervisors such as supervise and svscan from Daniel J. Bernstein's daemontools package, or the AIX process monitor.

--no-process-group

Do not create a new process group for winbindd.

-n|--no-caching

Disable some caching. This means winbindd will often have to wait for a response from the domain controller before it can respond to a client and this thus makes things slower. The results will however be more accurate, since results from the cache might not be up-to-date. This might also temporarily hang winbindd if the DC doesn't respond. This does not disable the samlogon cache, which is required for group membership tracking in trusted environments.

-d|--debuglevel=DEBUGLEVEL, --debug-stdout

level is an integer from 0 to 10. The default value if this parameter is not specified is 0. The higher this value, the more detail will be logged to the log files about the activities of the server. At level 0, only critical errors and serious warnings will be logged. Level 1 is a reasonable level for day-to-day running - it generates a small amount of information about operations carried out.

Levels above 1 will generate considerable amounts of log data, and should only be used when investigating a problem. Levels above 3 are designed for use only by developers and generate HUGE amounts of log data, most of which is extremely cryptic.

Note that specifying this parameter here will override the log level parameter in the /etc/samba/smb.conf file. This will redirect debug output to STDOUT. By default server daemons are logging to a log file.

--configfile=CONFIGFILE

The file specified contains the configuration details required by the server. The information in this file includes server-specific information such as what printcap file to use, as well as descriptions of all the services that the server is to provide. See /etc/samba/smb.conf for more information. The default configuration file name is determined at compile time.

--option=<name>=<value>

Set the smb.conf(5) option "<name>" to value "<value>" from the command line. This overrides compiled-in defaults and options read from the configuration file. If a name or a value includes a space, wrap whole --option=name=value into quotes.

-l|--log-basename=logdirectory

Base directory name for log/debug files. The parent process uses filename log.winbindd, the child process uses filename log.wb-<name>. The log file is never removed by winbindd.

--leak-report

Enable talloc leak reporting on exit.

--leak-report-full

Enable full talloc leak reporting on exit.

-V|--version

Prints the program version number.

-?|--help

Print a summary of command line options.

--usage

Display brief usage message.

## NAME AND ID RESOLUTION
Users and groups on a Windows NT server are assigned a security id (SID) which is globally unique when the user or group is created. To convert the Windows NT user or group into a unix user or group, a mapping between SIDs and unix user and group ids is required. This is one of the jobs that winbindd performs.

As winbindd users and groups are resolved from a server, user and group ids are allocated from a specified range. This is done on a first come, first served basis, although all existing users and groups will be mapped as soon as a client performs a user or group enumeration command. The allocated unix ids are stored in a database and will be remembered.

WARNING: The SID to unix id database is the only location where the user and group mappings are stored by winbindd. If this store is deleted or corrupted, there is no way for winbindd to determine which user and group ids correspond to Windows NT user and group rids.

## CONFIGURATION
Configuration of the winbindd daemon is done through configuration parameters in the smb.conf(5) file. All parameters should be specified in the [global] section of smb.conf.

•winbind separator

•idmap config * : range

•idmap config * : backend

•winbind cache time

•winbind enum users

•winbind enum groups

•template homedir

•template shell

•winbind use default domain

•winbind: rpc only Setting this parameter forces winbindd to use RPC instead of LDAP to retrieve information from Domain Controllers.

## EXAMPLE SETUP
To setup winbindd for user and group lookups plus authentication from a domain controller use something like the following setup. This was tested on an early Red Hat Linux box.

In /etc/nsswitch.conf put the following:

```
passwd: files winbind
group:  files winbind
```

In /etc/pam.d/* replace the auth lines with something like this:

```
auth  required    /lib/security/pam_securetty.so
auth  required	  /lib/security/pam_nologin.so
auth  sufficient  /lib/security/pam_winbind.so
auth  required    /lib/security/pam_unix.so \

                  use_first_pass shadow nullok
```

Note

The PAM module pam_unix has recently replaced the module pam_pwdb. Some Linux systems use the module pam_unix2 in place of pam_unix.

Note in particular the use of the sufficient keyword and the use_first_pass keyword.

Now replace the account lines with this:

account required /lib/security/pam_winbind.so

The next step is to join the domain. To do that use the net program like this:

net join -S PDC -U Administrator

The username after the -U can be any Domain user that has administrator privileges on the machine. Substitute the name or IP of your PDC for "PDC".

Next copy libnss_winbind.so to /lib and pam_winbind.so to /lib/security. A symbolic link needs to be made from /lib/libnss_winbind.so to /lib/libnss_winbind.so.2. If you are using an older version of glibc then the target of the link should be /lib/libnss_winbind.so.1.

Finally, setup a smb.conf(5) containing directives like the following:

```
[global]
	winbind separator = +

        winbind cache time = 10

        template shell = /bin/bash

        template homedir = /home/%D/%U

        idmap config * : range = 10000-20000

        workgroup = DOMAIN

        security = domain

        password server = *
```

Now start winbindd and you should find that your user and group database is expanded to include your NT users and groups, and that you can login to your unix box as a domain user, using the DOMAIN+user syntax for the username. You may wish to use the commands getent passwd and getent group to confirm the correct operation of winbindd.

## NOTES
The following notes are useful when configuring and running winbindd:

PAM is really easy to misconfigure. Make sure you know what you are doing when modifying PAM configuration files. It is possible to set up PAM such that you can no longer log into your system.

If more than one UNIX machine is running winbindd, then in general the user and groups ids allocated by winbindd will not be the same. The user and group ids will only be valid for the local machine, unless a shared idmap config * : backend is configured.

If the Windows NT SID to UNIX user and group id mapping file is damaged or destroyed then the mappings will be lost.

## SIGNALS
The following signals can be used to manipulate the winbindd daemon.

SIGHUP

Reload the smb.conf(5) file and apply any parameter changes to the running version of winbindd. This signal also clears any cached user and group information. The list of other domains trusted by winbindd is also reloaded. Instead of sending a SIGHUP signal, a request to reload configuration file may be sent using smbcontrol(1) program.

SIGUSR2

The SIGUSR2 signal will cause winbindd to write status information to the winbind log file. Log files are stored in the filename specified by the log file parameter.

## FILES
/etc/nsswitch.conf(5)

Name service switch configuration file.

/run/samba/winbindd/pipe

The UNIX pipe over which clients communicate with the winbindd program. For security reasons, the winbind client will only attempt to connect to the winbindd daemon if both the /run/samba/winbindd directory and /run/samba/winbindd/pipe file are owned by root. winbindd socket directory overrides this default.

$STATEDIR/winbindd_privileged/pipe

The UNIX pipe over which 'privileged' clients communicate with the winbindd program. For security reasons, access to some winbindd functions - like those needed by the ntlm_auth utility - is restricted. By default, only users in the 'root' group will get this access, however the administrator may change the group permissions on $STATEDIR/winbindd_privileged to allow programs like 'squid' to use ntlm_auth. Note that the winbind client will only attempt to connect to the winbindd daemon if both the $STATEDIR/winbindd_privileged directory and $STATEDIR/winbindd_privileged/pipe file are owned by root. state dir controls what $STATEDIR refers to.

/lib/libnss_winbind.so.X

Implementation of name service switch library.

$STATEDIR/winbindd_idmap.tdb

Storage for the Windows NT rid to UNIX user/group id mapping. The directory is specified when Samba is initially compiled using the --with-statedir option or state dir. The default directory in this installation is /var/lib/samba.

$LOCKDIR/winbindd_cache.tdb

Storage for cached user and group information.

## VERSION
This man page is part of version 4.21.9-alt3.p11.1 of the Samba suite.

## SEE ALSO
nsswitch.conf(5), samba(7), wbinfo(1), ntlm_auth(8), smb.conf(5), pam_winbind(8)

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.

wbinfo and winbindd were written by Tim Potter.

The conversion to DocBook for Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 for Samba 3.0 was done by Alexander Bokovoy.


title: winbind_krb5_localauth(8)

text:
# winbind_krb5_localauth(8)

## NAME
winbind_krb5_localauth - A plugin for MIT Kerberos for mapping user accounts.

## DESCRIPTION
This plugin is part of the samba(7) suite.

winbind_krb5_localauth is a plugin that permits the MIT Kerberos libraries that Kerberos principals can be validated against local user accounts.

## PREREQUISITES
MIT Kerberos (at least version 1.12) is required.

The plugin queries the winbindd(8) daemon which needs to be configured and started separately.

The following sections needs to be added to the krb5.conf file.

```
[plugins]
	localauth = {
		module = winbind:/usr/lib64/samba/krb5/winbind_krb5_localauth.so
		enable_only = winbind
	}

```

## VERSION
This man page is part of version 4.21.9-alt3.p11.1 of the Samba suite.

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.

The winbind_krb5_localauth manpage was written by Andreas Schneider.


title: winbind_krb5_locator(8)

text:
# winbind_krb5_locator(8)

## NAME
winbind_krb5_locator - A plugin for MIT and Heimdal Kerberos for detecting KDCs using Windows semantics.

## DESCRIPTION
This plugin is part of the samba(7) suite.

winbind_krb5_locator is a plugin that permits MIT and Heimdal Kerberos libraries to detect Kerberos Servers (for the KDC and kpasswd service) using the same semantics that other tools of the Samba suite use. This include site-aware DNS service record lookups and caching of closest dc. The plugin uses the public locator API provided by most modern Kerberos implementations.

## PREREQUISITES
MIT Kerberos (at least version 1.5) or Heimdal Kerberos (at least version 1.0) is required.

The plugin queries the winbindd(8) daemon which needs to be configured and started separately.

The winbind_krb5_locator.so file needs to be manually copied to the plugin directory of the system Kerberos library. For MIT Kerberos this is often: /usr/lib/krb5/plugins/libkrb5/. For Heimdal Kerberos this is often: /usr/lib/plugin/krb5/. Please check your local Kerberos installation for the correct paths. No modification in /etc/krb5.conf is required to enable the use of this plugin.

After copying the locator plugin to the appropriate plugin directory it should immediately be available for use. Users should be able to kinit into their kerberized Windows environment without any modification or servers being put manually into /etc/krb5.conf.

## VERSION
This man page is part of version 4.21.9-alt3.p11.1 of the Samba suite.

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.

The winbind_krb5_locator manpage was written by Guenther Deschner.


saned

package: sane-server

title: saned(8)

summary: SANE network daemon

text:
# saned(8)

## NAME
saned - SANE network daemon

## SYNOPSIS
saned [ -a [ username ] ] [ -u username ] [ -b address ] [ -p port ] [ -l ] [ -D ] [ -o ] [ -d n ] [ -e ] [ -h ] [ -B buffer-size ]

## DESCRIPTION
saned is the SANE (Scanner Access Now Easy) daemon that allows remote clients to access image acquisition devices available on the local host.

## OPTIONS
saned recognises the following options:

-a [username], --alone[=username]

is equivalent to the combination of -l -D -u username options. However, username is optional and running user will only be set when specified.

-u username, --user=username

requests that saned drop root privileges and run as the user (and group) associated with username after binding.

-b address, --bind=address

tells saned to bind to the address given.

-p port, --port=port

tells saned to listen on the port given. A value of 0 tells saned to pick an unused port. The default is the sane-port (6566).

-l, --listen

requests that saned run in standalone daemon mode. In this mode, saned will listen for incoming client connections; inetd(8) is not required for saned operations in this mode.

-D, --daemonize

will request saned to detach from the console and run in the background.

-n, --allow-network

allows saned to use network scanners. By default this is forbidden to prevent saned from contacting itself. When enabled, the configuration of the sane-net(5) backend should not mention the address on which saned is listening.

-o, --once

requests that saned exits after the first client disconnects. This is useful for debugging.

-d n, --debug=n

sets the level of saned debug output to n. When compiled with debugging enabled, this flag may be followed by a number to request more or less debug info. The larger the number, the more verbose the debug output. E.g., -d128 will request output of all debug info. A level of 0 produces no output at all. The default value is 2.

-e, --stderr

will divert saned debug output to stderr instead of the syslog default.

-B, --buffer-size=buffer-size

specifies the size of the read buffer used for communication with the backend in KB. Default value is 1MB.

-h, --help

displays a short help message.

## CONFIGURATION
The saned.conf configuration file contains both options for the daemon and the access list.

data_portrange = min_port - max_port

Specify the port range to use for the data connection. Pick a port range between 1024 and 65535; don't pick a too large port range, as it may have performance issues. Use this option if your saned server is sitting behind a firewall. If that firewall is a Linux machine, we strongly recommend using the Netfilter nf_conntrack_sane module instead.

data_connect_timeout = timeout

Specify the time in milliseconds that saned will wait for a data connection. Without this option, if the data connection is not done before the scanner reaches the end of scan, the scanner will continue to scan past the end and may damage it depending on the backend. Specify zero to have the old behavior. The default is 4000ms.

The access list is a list of host names, IP addresses or IP subnets (CIDR notation) that are permitted to use local SANE devices. IPv6 addresses must be enclosed in brackets, and should always be specified in their compressed form. Connections from localhost are always permitted. Empty lines and lines starting with a hash mark (#) are ignored. A line containing the single character ``+'' is interpreted to match any hostname. This allows any remote machine to use your scanner and may present a security risk, so this shouldn't be used unless you know what you're doing.

A sample configuration file is shown below:

\# Daemon options

data_portrange = 10000 - 10100

\# Access list

scan-client.somedomain.firm

\# this is a comment

192.168.0.1

192.168.2.12/29

[::1]

[2001:db8:185e::42:12]/64

The case of the host names does not matter, so AHost.COM is considered identical to ahost.com.

## FILES
/etc/hosts.equiv

The hosts listed in this file are permitted to access all local SANE devices. Caveat: this file imposes serious security risks and its use is not recommended.

/etc/sane.d/saned.conf

Contains a list of hosts permitted to access local SANE devices (see also description of SANE_CONFIG_DIR below).

/etc/sane.d/saned.users

If this file contains lines of the form user:password:backend

access to the listed backends is restricted. A backend may be listed multiple times for different user/password combinations. The server uses MD5 hashing if supported by the client.

## ENVIRONMENT
SANE_CONFIG_DIR

This environment variable specifies the list of directories that may contain the configuration file. On *NIX systems, the directories are separated by a colon (`:'), under OS/2, they are separated by a semi-colon (`;'). If this variable is not set, the configuration file is searched in two default directories: first, the current working directory (".") and then in /etc/sane.d. If the value of the environment variable ends with the directory separator character, then the default directories are searched after the explicitly specified directories. For example, setting SANE_CONFIG_DIR to "/tmp/config:" would result in directories tmp/config, ., and /etc/sane.d being searched (in this order).

## NOTES
saned does not provide confidentiality when communicating with clients. If saned is exposed directly on the network, other users may be able to intercept scanned images, or learn passwords for connecting to saned, with little effort. Client systems should connect to saned through a secure tunnel to the server instead.

saned is not a trusted program and should not run with root privileges.

Refer to /usr/share/doc/sane-backends/saned/saned.install.md for details on configuring saned as a service.

## SEE ALSO
sane(7), scanimage(1), xscanimage(1), xcam(1), sane-dll(5), sane-net(5), sane-"backendname"(5), inetd(8), xinetd(8), systemd(1)

http://www.penguin-breeder.org/?page=sane-net

## AUTHOR
David Mosberger


sanlk-reset

package: sanlk-reset

title: sanlk-reset(8)

summary: host reset program

text:
# sanlk-reset(8)

## NAME
sanlk-reset - host reset program

## SYNOPSIS
sanlk-reset [OPTIONS] action lockspace_name ...

## DESCRIPTION
The sanlk-reset program sets events in specified sanlock lockspaces. Events are defined to cause sanlk-resetd on another host to:

- use wdmd/watchdog to reset the host

- use /proc/sysrq-trigger to reboot the host

Both hosts must be operational and have continued access to a common lockspace for the reset request to succeed. After setting the event, the sanlk-reset program monitors the host status in the sanlock lockspace until the target host is dead.

The sanlk-reset program can also be run on the same host as sanlk-resetd to update which lockspaces the local sanlk-resetd is watching for events.

## OPTIONS
--version, -V

Print version.

--help, -h

Print usage.

### Reset another host
The event is set in each lockspace specified. The target host may have a different host id in each lockspace.

sanlk-reset reset lockspace_name:host_id ...

--host-id, -i num

Host id to reset. (Use only with single lockspace name.)

--generation, -g num

Generation of host. (Use only with single lockspace name.)

--sysrq-reboot, -b 0|1

Enable/Disable (1/0) use of /proc/sysrq-trigger to reboot.

--resource-mode, -R 0|1

Resource leases are used (1) or not used (0) to protect storage.

--native-timeout, -t num

Disable native timeout by setting to 0.

### Update the local sanlk-resetd

to watch new lockspaces for reset events:

sanlk-reset reg lockspace_name ...

to not watch lockspaces for reset events:

sanlk-reset end lockspace_name ...

to clear all lockspaces being watched:

sanlk-reset clear all

## SEE ALSO
sanlk-resetd(8) sanlock(8) wdmd(8)


sanlk-resetd

title: sanlk-resetd(8)

summary: host reset daemon

text:
# sanlk-resetd(8)

## NAME
sanlk-resetd - host reset daemon

## SYNOPSIS
sanlk-resetd [OPTIONS] lockspace_name ...

## DESCRIPTION
The sanlk-resetd daemon gets events from specified sanlock lockspaces. Events are defined to cause sanlk-resetd to:

- use wdmd/watchdog to reset the host

- use /proc/sysrq-trigger to reboot the host

The sanlk-reset program can be run on another host to request that sanlk-resetd reset the host it is running on. Both hosts must be operational and have continued access to a common lockspace for the reset request to succeed. After setting the event, the sanlk-reset program monitors the host status in the sanlock lockspace until the target host is dead.

The sanlk-reset program can also be run on the same host as sanlk-resetd to update which lockspaces the local sanlk-resetd is watching for events.

## OPTIONS
--version, -V

Print version.

--help, -h

Print usage.

--foreground, -f

Don't fork.

--daemon-debug, -D

Enable debugging to stderr and don't fork.

--sysrq-reboot, -b 0|1

Enable/Disable (1/0) use of /proc/sysrq-trigger to reboot.

--sysrq-delay, -d sec

Delay this many seconds before using /proc/sysrq-trigger.

--resource-mode, -R 0|1

Resource leases are used (1) or not used (0) to protect storage.

## SEE ALSO
sanlk-reset(8) sanlock(8) wdmd(8)


sanlock

package: sanlock

title: sanlock(8)

summary: shared storage lock manager

text:
# sanlock(8)

## NAME
sanlock - shared storage lock manager

## SYNOPSIS
sanlock [COMMAND] [ACTION] ...

## DESCRIPTION
sanlock is a lock manager built on shared storage. Hosts with access to the storage can perform locking. An application running on the hosts is given a small amount of space on the shared block device or file, and uses sanlock for its own application-specific synchronization. Internally, the sanlock daemon manages locks using two disk-based lease algorithms: delta leases and paxos leases.

•

delta leases are slow to acquire and demand regular i/o to shared storage. sanlock only uses them internally to hold a lease on its "host_id" (an integer host identifier from 1-2000). They prevent two hosts from using the same host identifier. The delta lease renewals also indicate if a host is alive. ("Light-Weight Leases for Storage-Centric Coordination", Chockler and Malkhi.)

•

paxos leases are fast to acquire and sanlock makes them available to applications as general purpose resource leases. The disk paxos algorithm uses host_id's internally to represent different hosts, and the owner of a paxos lease. delta leases provide unique host_id's for implementing paxos leases, and delta lease renewals serve as a proxy for paxos lease renewal. ("Disk Paxos", Eli Gafni and Leslie Lamport.)

Externally, the sanlock daemon exposes a locking interface through libsanlock in terms of "lockspaces" and "resources". A lockspace is a locking context that an application creates for itself on shared storage. When the application on each host is started, it "joins" the lockspace. It can then create "resources" on the shared storage. Each resource represents an application-specific entity. The application can acquire and release leases on resources.

To use sanlock from an application:

•

Allocate shared storage for an application, e.g. a shared LUN or LV from a SAN, or files from NFS.

•

Provide the storage to the application.

•

The application uses this storage with libsanlock to create a lockspace and resources for itself.

•

The application joins the lockspace when it starts.

•

The application acquires and releases leases on resources.

How lockspaces and resources translate to delta leases and paxos leases within sanlock:

Lockspaces

•

A lockspace is based on delta leases held by each host using the lockspace.

•

A lockspace is a series of 2000 delta leases on disk, and requires 1MB of storage. (See Storage below for size variations.)

•

A lockspace can support up to 2000 concurrent hosts using it, each using a different delta lease.

•

Applications can i) create, ii) join and iii) leave a lockspace, which corresponds to i) initializing the set of delta leases on disk, ii) acquiring one of the delta leases and iii) releasing the delta lease.

•

When a lockspace is created, a unique lockspace name and disk location is provided by the application.

•

When a lockspace is created/initialized, sanlock formats the sequence of 2000 on-disk delta lease structures on the file or disk, e.g. /mnt/leasefile (NFS) or /dev/vg/lv (SAN).

•

The 2000 individual delta leases in a lockspace are identified by number: 1,2,3,...,2000.

•

Each delta lease is a 512 byte sector in the 1MB lockspace, offset by its number, e.g. delta lease 1 is offset 0, delta lease 2 is offset 512, delta lease 2000 is offset 1023488. (See Storage below for size variations.)

•

When an application joins a lockspace, it must specify the lockspace name, the lockspace location on shared disk/file, and the local host's host_id. sanlock then acquires the delta lease corresponding to the host_id, e.g. joining the lockspace with host_id 1 acquires delta lease 1.

•

The terms delta lease, lockspace lease, and host_id lease are used interchangeably.

•

sanlock acquires a delta lease by writing the host's unique name to the delta lease disk sector, reading it back after a delay, and verifying it is the same.

•

If a unique host name is not specified, sanlock uses the product_uuid if one is available, otherwise generates a uuid to use as the host's name. The delta lease algorithm depends on hosts using unique names.

•

The application on each host should be configured with a unique host_id, where the host_id is an integer 1-2000.

•

If hosts are misconfigured and have the same host_id, the delta lease algorithm is designed to detect this conflict, and only one host will be able to acquire the delta lease for that host_id.

•

A delta lease ensures that a lockspace host_id is being used by a single host with the unique name specified in the delta lease.

•

Resolving delta lease conflicts is slow, because the algorithm is based on waiting and watching for some time for other hosts to write to the same delta lease sector. If multiple hosts try to use the same delta lease, the delay is increased substantially. So, it is best to configure applications to use unique host_id's that will not conflict.

•

After sanlock acquires a delta lease, the lease must be renewed until the application leaves the lockspace (which corresponds to releasing the delta lease on the host_id.)

•

sanlock renews delta leases every 20 seconds (by default) by writing a new timestamp into the delta lease sector.

•

When a host acquires a delta lease in a lockspace, it can be referred to as "joining" the lockspace. Once it has joined the lockspace, it can use resources associated with the lockspace.

Resources

•

A lockspace is a context for resources that can be locked and unlocked by an application.

•

sanlock uses paxos leases to implement leases on resources. The terms paxos lease and resource lease are used interchangeably.

•

A paxos lease exists on shared storage and requires 1MB of space. It contains a unique resource name and the name of the lockspace.

•

An application assigns its own meaning to a sanlock resource and the leases on it. A sanlock resource could represent some shared object like a file, or some unique role among the hosts.

•

Resource leases are associated with a specific lockspace and can only be used by hosts that have joined that lockspace (they are holding a delta lease on a host_id in that lockspace.)

•

An application must keep track of the disk locations of its lockspaces and resources. sanlock does not maintain any persistent index or directory of lockspaces or resources that have been created by applications, so applications need to remember where they have placed their own leases (which files or disks and offsets).

•

sanlock does not renew paxos leases directly (although it could). Instead, the renewal of a host's delta lease represents the renewal of all that host's paxos leases in the associated lockspace. In effect, many paxos lease renewals are factored out into one delta lease renewal. This reduces i/o when many paxos leases are used.

•

The disk paxos algorithm allows multiple hosts to all attempt to acquire the same paxos lease at once, and will produce a single winner/owner of the resource lease. (Shared resource leases are also possible in addition to the default exclusive leases.)

•

The disk paxos algorithm involves a specific sequence of reading and writing the sectors of the paxos lease disk area. Each host has a dedicated 512 byte sector in the paxos lease disk area where it writes its own "ballot", and each host reads the entire disk area to see the ballots of other hosts. The first sector of the disk area is the "leader record" that holds the result of the last paxos ballot. The winner of the paxos ballot writes the result of the ballot to the leader record (the winner of the ballot may have selected another contending host as the owner of the paxos lease.)

•

After a paxos lease is acquired, no further i/o is done in the paxos lease disk area.

•

Releasing the paxos lease involves writing a single sector to clear the current owner in the leader record.

•

If a host holding a paxos lease fails, the disk area of the paxos lease still indicates that the paxos lease is owned by the failed host. If another host attempts to acquire the paxos lease, and finds the lease is held by another host_id, it will check the delta lease of that host_id. If the delta lease of the host_id is being renewed, then the paxos lease is owned and cannot be acquired. If the delta lease of the owner's host_id has expired, then the paxos lease is expired and can be taken (by going through the paxos lease algorithm.)

•

The "interaction" or "awareness" between hosts of each other is limited to the case where they attempt to acquire the same paxos lease, and need to check if the referenced delta lease has expired or not.

•

When hosts do not attempt to lock the same resources concurrently, there is no host interaction or awareness. The state or actions of one host have no effect on others.

•

To speed up checking delta lease expiration (in the case of a paxos lease conflict), sanlock keeps track of past renewals of other delta leases in the lockspace.

Resource Index

The resource index (rindex) is an optional sanlock feature that applications can use to keep track of resource lease offsets. Without the rindex, an application must keep track of where its resource leases exist on disk and find available locations when creating new leases.

The sanlock rindex uses two align-size areas on disk following the lockspace. The first area holds rindex entries; each entry records a resource lease name and location. The second area holds a private paxos lease, used by sanlock internally to protect rindex updates.

The application creates the rindex on disk with the "format" function. Format is a disk-only operation and does not interact with the live lockspace, so it can be called without first calling add_lockspace. The application needs to follow the convention of writing the lockspace at the start of the device (offset 0) and formatting the rindex immediately following the lockspace area. When formatting, the application must set flags for sector size and align size to match those for the lockspace.

To use the rindex, the application:

•

Uses the "create" function to create a new resource lease on disk. This takes the place of the write_resource function. The create function requires the location of the rindex and the name of the new resource lease. sanlock finds a free lease area, writes the new resource lease at that location, updates the rindex with the name:offset, and returns the offset to the caller. The caller uses this offset when acquiring the resource lease.

•

Uses the "delete" function to remove a resource disk on disk (also corresponding to the write_resource function.) sanlock clears the resource lease and the rindex entry for it. A subsequent call to create may use this same disk location for a different resource lease.

•

Uses the "lookup" function to discover the offset of a resource lease given the resource lease name. The caller would typically call this prior to acquiring the resource lease.

•

Uses the "rebuild" function to recreate the rindex if it is damaged or becomes inconsistent. This function scans the disk for resource leases and creates new rindex entries to match the leases it finds.

•

The "update" function manipulates rindex entries directly and should not normally be used by the application. In normal usage, the create and delete functions manipulate rindex entries. Update is mainly useful for testing or repairs.

Expiration

•

If a host fails to renew its delta lease, e.g. it looses access to the storage, its delta lease will eventually expire and another host will be able to take over any resource leases held by the host. sanlock must ensure that the application on two different hosts is not holding and using the same lease concurrently.

•

When sanlock has failed to renew a delta lease for a period of time, it will begin taking measures to stop local processes (applications) from using any resource leases associated with the expiring lockspace delta lease. sanlock enters this "recovery mode" well ahead of the time when another host could take over the locally owned leases. sanlock must have sufficient time to stop all local processes that are using the expiring leases.

•

sanlock uses three methods to stop local processes that are using expiring leases: 1. Graceful shutdown. sanlock will execute a "graceful shutdown" program that the application previously specified for this case. The shutdown program tells the application to shut down because its leases are expiring. The application must respond by stopping its activities and releasing its leases (or exit). If an application does not specify a graceful shutdown program, sanlock sends SIGTERM to the process instead. The process must release its leases or exit in a prescribed amount of time (see -g), or sanlock proceeds to the next method of stopping.

2. Forced shutdown. sanlock will send SIGKILL to processes using the expiring leases. The processes have a fixed amount of time to exit after receiving SIGKILL. If any do not exit in this time, sanlock will proceed to the next method.

3. Host reset. sanlock will trigger the host's watchdog device to forcibly reset it. sanlock carefully manages the timing of the watchdog device so that it fires shortly before any other host could take over the resource leases held by local processes.

Failures

If a process holding resource leases fails or exits without releasing its leases, sanlock will release the leases for it automatically (unless persistent resource leases were used.)

If the sanlock daemon cannot renew a lockspace delta lease for a specific period of time (see Expiration), sanlock will enter "recovery mode" where it attempts to stop and/or kill any processes holding resource leases in the expiring lockspace. If the processes do not exit in time, sanlock will force the host to be reset using the local watchdog device.

If the sanlock daemon crashes or hangs, it will not renew the expiry time of the per-lockspace connections it had to the wdmd daemon. This will lead to the expiration of the local watchdog device, and the host will be reset.

Watchdog

sanlock uses the wdmd(8) daemon to access /dev/watchdog. wdmd multiplexes multiple timeouts onto the single watchdog timer. This is required because delta leases for each lockspace are renewed and expire independently.

sanlock maintains a wdmd connection for each lockspace delta lease being renewed. Each connection has an expiry time for some seconds in the future. After each successful delta lease renewal, the expiry time is renewed for the associated wdmd connection. If wdmd finds any connection expired, it will not renew the /dev/watchdog timer. Given enough successive failed renewals, the watchdog device will fire and reset the host. (Given the multiplexing nature of wdmd, shorter overlapping renewal failures from multiple lockspaces could cause spurious watchdog firing.)

The direct link between delta lease renewals and watchdog renewals provides a predictable watchdog firing time based on delta lease renewal timestamps that are visible from other hosts. sanlock knows the time the watchdog on another host has fired based on the delta lease time. Furthermore, if the watchdog device on another host fails to fire when it should, the continuation of delta lease renewals from the other host will make this evident and prevent leases from being taken from the failed host.

If sanlock is able to stop/kill all processing using an expiring lockspace, the associated wdmd connection for that lockspace is removed. The expired wdmd connection will no longer block /dev/watchdog renewals, and the host should avoid being reset.

Storage

The sector size and the align size should be specified when creating lockspaces and resources (and rindex). The "align size" is the size on disk of a lockspace or a resource, i.e. the amount of disk space it uses. Lockspaces and resources should use matching sector and align sizes, and must use offsets in multiples of the align size. The max number of hosts that can use a lockspace or resource depends on the combination of sector size and align size, shown below. The host_id of hosts using the lockspace can be no larger than the max_hosts value for the lockspace.

Accepted combinations of sector size and align size, and the corresponding max_hosts (and max host_id) are:

sector_size 512, align_size 1M, max_hosts 2000

sector_size 4096, align_size 1M, max_hosts 250

sector_size 4096, align_size 2M, max_hosts 500

sector_size 4096, align_size 4M, max_hosts 1000

sector_size 4096, align_size 8M, max_hosts 2000

When sector_size and align_size are not specified, the behavior matches the behavior before these sizes could be configured: on devices which report sector size 512, 512/1M/2000 is used, on devices which report sector size 4096, 4096/8M/2000 is used, and on files, 512/1M/2000 is always used. (Other combinations are not compatible with sanlock version 3.6 or earlier.)

Using sanlock on shared block devices that do host based mirroring or replication is not likely to work correctly. When using sanlock on shared files, all sanlock io should go to one file server.

Example

This is an example of creating and using lockspaces and resources from the command line. (Most applications would use sanlock through libsanlock rather than through the command line.)

1.

Allocate shared storage for sanlock leases. This example assumes 512 byte sectors on the device, in which case the lockspace needs 1MB and each resource needs 1MB.

The example shared block device accessible to all hosts is /dev/leases.

2.

Start sanlock on all hosts. The -w 0 disables use of the watchdog for testing.

```
# sanlock daemon -w 0
```

3.

Start a dummy application on all hosts. This sanlock command registers with sanlock, then execs the sleep command which inherits the registered fd. The sleep process acts as the dummy application. Because the sleep process is registered with sanlock, leases can be acquired for it.

```
# sanlock client command -c /bin/sleep 600 &
```

4.

Create a lockspace for the application (from one host). The lockspace is named "test".

```
# sanlock client init -s test:0:/dev/leases:0
```

5.

Join the lockspace for the application. Use a unique host_id on each host.

```
host1:
# sanlock client add_lockspace -s test:1:/dev/leases:0
host2:
# sanlock client add_lockspace -s test:2:/dev/leases:0
```

6.

Create two resources for the application (from one host). The resources are named "RA" and "RB". Offsets are used on the same device as the lockspace. Different LVs or files could also be used.

```
# sanlock client init -r test:RA:/dev/leases:1048576
# sanlock client init -r test:RB:/dev/leases:2097152
```

7.

Acquire resource leases for the application on host1. Acquire an exclusive lease (the default) on the first resource, and a shared lease (SH) on the second resource.

```
# export P=`pidof sleep`
# sanlock client acquire -r test:RA:/dev/leases:1048576 -p $P
# sanlock client acquire -r test:RB:/dev/leases:2097152:SH -p $P
```

8.

Acquire resource leases for the application on host2. Acquiring the exclusive lease on the first resource will fail because it is held by host1. Acquiring the shared lease on the second resource will succeed.

```
# export P=`pidof sleep`
# sanlock client acquire -r test:RA:/dev/leases:1048576 -p $P
# sanlock client acquire -r test:RB:/dev/leases:2097152:SH -p $P
```

9.

Release resource leases for the application on both hosts. The sleep pid could also be killed, which will result in the sanlock daemon releasing its leases when it exits.

```
# sanlock client release -r test:RA:/dev/leases:1048576 -p $P
# sanlock client release -r test:RB:/dev/leases:2097152 -p $P
```

10.

Leave the lockspace for the application.

```
host1:
# sanlock client rem_lockspace -s test:1:/dev/leases:0
host2:
# sanlock client rem_lockspace -s test:2:/dev/leases:0
```

11.

Stop sanlock on all hosts.

```
# sanlock shutdown
```

## OPTIONS
COMMAND can be one of three primary top level choices

sanlock daemon start daemon

sanlock client send request to daemon (default command if none given)

sanlock direct access storage directly (no coordination with daemon)

### Daemon Command
sanlock daemon [options]

-D no fork and print all logging to stderr

-Q 0|1 quiet error messages for common lock contention

-R 0|1 renewal debugging, log debug info for each renewal

-L pri write logging at priority level and up to logfile (-1 none)

-S pri write logging at priority level and up to syslog (-1 none)

-U uid user id

-G gid group id

-H num renewal history size

-t num max worker threads

-g sec seconds for graceful recovery

-w 0|1 use watchdog through wdmd

-o sec io timeout

-h 0|1 use high priority (RR) scheduling

-l num use mlockall (0 none, 1 current, 2 current and future)

-b sec seconds a host id bit will remain set in delta lease bitmap

-e str unique local host name used in delta leases as host_id owner

### Client Command
sanlock client action [options]

sanlock client status

Print processes, lockspaces, and resources being managed by the sanlock daemon. Add -D to show extra internal daemon status for debugging. Add -o p to show resources by pid, or -o s to show resources by lockspace.

sanlock client host_status

Print state of host_id delta leases read during the last renewal. State of all lockspaces is shown (use -s to select one). Add -D to show extra internal daemon status for debugging.

sanlock client gets

Print lockspaces being managed by the sanlock daemon. The LOCKSPACE string will be followed by ADD or REM if the lockspace is currently being added or removed. Add -h 1 to also show hosts in each lockspace.

sanlock client renewal -s LOCKSPACE

Print a history of renewals with timing details. See the Renewal history section below.

sanlock client log_dump

Print the sanlock daemon internal debug log.

sanlock client shutdown

Ask the sanlock daemon to exit. Without the force option (-f 0), the command will be ignored if any lockspaces exist. With the force option (-f 1), any registered processes will be killed, their resource leases released, and lockspaces removed. With the wait option (-w 1), the command will wait for a result from the daemon indicating that it has shut down and is exiting, or cannot shut down because lockspaces exist (command fails).

sanlock client init -s LOCKSPACE

Tell the sanlock daemon to initialize a lockspace on disk. The -o option can be used to specify the io timeout to be written in the host_id leases. The -Z and -A options can be used to specify the sector size and align size, and both should be set together. (Also see sanlock direct init.)

sanlock client init -r RESOURCE

Tell the sanlock daemon to initialize a resource lease on disk. The -Z and -A options can be used to specify the sector size and align size, and both should be set together. (Also see sanlock direct init.)

sanlock client read -s LOCKSPACE

Tell the sanlock daemon to read a lockspace from disk. Only the LOCKSPACE path and offset are required. If host_id is zero, the first record at offset (host_id 1) is used. The complete LOCKSPACE is printed. Add -D to print other details. (Also see sanlock direct read_leader.)

sanlock client read -r RESOURCE

Tell the sanlock daemon to read a resource lease from disk. Only the RESOURCE path and offset are required. The complete RESOURCE is printed. Add -D to print other details. (Also see sanlock direct read_leader.)

sanlock client add_lockspace -s LOCKSPACE

Tell the sanlock daemon to acquire the specified host_id in the lockspace. This will allow resources to be acquired in the lockspace. The -o option can be used to specify the io timeout of the acquiring host, and will be written in the host_id lease.

sanlock client inq_lockspace -s LOCKSPACE

Inquire about the state of the lockspace in the sanlock daemon, whether it is being added or removed, or is joined.

sanlock client rem_lockspace -s LOCKSPACE

Tell the sanlock daemon to release the specified host_id in the lockspace. Any processes holding resource leases in this lockspace will be killed, and the resource leases not released.

sanlock client command -r RESOURCE -c path args

Register with the sanlock daemon, acquire the specified resource lease, and exec the command at path with args. When the command exits, the sanlock daemon will release the lease. -c must be the final option.

sanlock client acquire -r RESOURCE -p pid

sanlock client release -r RESOURCE -p pid

Tell the sanlock daemon to acquire or release the specified resource lease for the given pid. The pid must be registered with the sanlock daemon. acquire can optionally take a versioned RESOURCE string RESOURCE:lver, where lver is the version of the lease that must be acquired, or fail. Use -C in place of -p to specify client_id.

sanlock client convert -r RESOURCE -p pid

Tell the sanlock daemon to convert the mode of the specified resource lease for the given pid. If the existing mode is exclusive (default), the mode of the lease can be converted to shared with RESOURCE:SH. If the existing mode is shared, the mode of the lease can be converted to exclusive with RESOURCE (no :SH suffix). Use -C in place of -p to specify client_id.

sanlock client inquire -p pid

Print the resource leases held the given pid. The format is a versioned RESOURCE string "RESOURCE:lver" where lver is the version of the lease held. Use -C in place of -p to specify client_id.

sanlock client request -r RESOURCE -f force_mode

Request the owner of a resource do something specified by force_mode. A versioned RESOURCE:lver string must be used with a greater version than is presently held. Zero lver and force_mode clears the request.

sanlock client examine -r RESOURCE

Examine the request record for the currently held resource lease and carry out the action specified by the requested force_mode.

sanlock client examine -s LOCKSPACE

Examine requests for all resource leases currently held in the named lockspace. Only lockspace_name is used from the LOCKSPACE argument.

sanlock client set_event -s LOCKSPACE -i host_id -g gen -e num -d num

Set an event for another host. When the sanlock daemon next renews its delta lease for the lockspace it will: set the bit for the host_id in its bitmap, and set the generation, event and data values in its own delta lease. An application that has registered for events from this lockspace on the destination host will get the event that has been set when the destination sees the event during its next delta lease renewal.

sanlock client set_config -s LOCKSPACE

Set a configuration value for a lockspace. Only lockspace_name is used from the LOCKSPACE argument. The USED flag has the same effect on a lockspace as a process holding a resource lease that will not exit. The USED_BY_ORPHANS flag means that an orphan resource lease will have the same effect as the USED.

-u 0|1 Set (1) or clear (0) the USED flag.

-O 0|1 Set (1) or clear (0) the USED_BY_ORPHANS flag.

sanlock client format -x RINDEX

Create a resource index on disk. Use -Z and -A to set the sector size and align size to match the lockspace.

sanlock client create -x RINDEX -e resource_name

Create a new resource lease on disk, using the rindex to find a free offset.

sanlock client delete -x RINDEX -e resource_name[:offset]

Delete an existing resource lease on disk.

sanlock client lookup -x RINDEX -e resource_name

Look up the offset of an existing resource lease by name on disk, using the rindex. With no -e option, lookup returns the next free lease offset. If -e specifes both name and offset, the lookup verifies both are correct.

sanlock client update -x RINDEX -e resource_name[:offset] [-z 0|1]

Add (-z 0) or remove (-z 1) an rindex entry on disk.

sanlock client rebuild -x RINDEX

Rebuild the rindex entries by scanning the disk for resource leases.

### Direct Command
sanlock direct action [options]

-o sec io timeout in seconds

sanlock direct init -s LOCKSPACE

sanlock direct init -r RESOURCE

Initialize storage for a lockspace or resource. Use the -Z and -A flags to specify the sector size and align size. The max hosts that can use the lockspace/resource (and the max possible host_id) is determined by the sector/align size combination. Possible combinations are: 512/1M, 4096/1M, 4096/2M, 4096/4M, 4096/8M. Lockspaces and resources both use the same amount of space (align_size) for each combination. When initializing a lockspace, sanlock initializes delta leases for max_hosts in the given space. When initializing a resource, sanlock initializes a single paxos lease in the space. With -s, the -o option specifies the io timeout to be written in the host_id leases. With -r, the -z 1 option invalidates the resource lease on disk so it cannot be used until reinitialized normally.

sanlock direct read_leader -s LOCKSPACE

sanlock direct read_leader -r RESOURCE

Read a leader record from disk and print the fields. The leader record is the single sector of a delta lease, or the first sector of a paxos lease.

sanlock direct dump path[:offset[:size]]

Read disk sectors and print leader records for delta or paxos leases. Add -f 1 to print the request record values for paxos leases, host_ids set in delta lease bitmaps, and rindex entries.

sanlock direct format -x RINDEX

sanlock direct lookup -x RINDEX -e resource_name

sanlock direct update -x RINDEX -e resource_name[:offset] [-z 0|1]

sanlock direct rebuild -x RINDEX

Access the resource index on disk without going through the sanlock daemon. This precludes using the internal paxos lease to protect rindex modifications. See client equivalents for descriptions.

### LOCKSPACE option string
-s lockspace_name:host_id:path:offset

lockspace_name name of lockspace

host_id local host identifier in lockspace

path path to storage to use for leases

offset offset on path (bytes)

### RESOURCE option string
-r lockspace_name:resource_name:path:offset

lockspace_name name of lockspace

resource_name name of resource

path path to storage to use leases

offset offset on path (bytes)

### RESOURCE option string with suffix
-r lockspace_name:resource_name:path:offset:lver

lver leader version

-r lockspace_name:resource_name:path:offset:SH

SH indicates shared mode

### RINDEX option string
-x lockspace_name:path:offset

lockspace_name name of lockspace

path path to storage to use for leases

offset offset on path (bytes) of rindex

### Defaults
sanlock help shows the default values for the options above.

sanlock version shows the build version.

## OTHER

### Request/Examine
The first part of making a request for a resource is writing the request record of the resource (the sector following the leader record). To make a successful request:

- RESOURCE:lver must be greater than the lver presently held by the other host. This implies the leader record must be read to discover the lver, prior to making a request.

- RESOURCE:lver must be greater than or equal to the lver presently written to the request record. Two hosts may write a new request at the same time for the same lver, in which case both would succeed, but the force_mode from the last would win.

- The force_mode must be greater than zero.

- To unconditionally clear the request record (set both lver and force_mode to 0), make request with RESOURCE:0 and force_mode 0.

The owner of the requested resource will not know of the request unless it is explicitly told to examine its resources via the "examine" api/command, or otherwise notfied.

The second part of making a request is notifying the resource lease owner that it should examine the request records of its resource leases. The notification will cause the lease owner to automatically run the equivalent of "sanlock client examine -s LOCKSPACE" for the lockspace of the requested resource.

The notification is made using a bitmap in each host_id delta lease. Each bit represents each of the possible host_ids (1-2000). If host A wants to notify host B to examine its resources, A sets the bit in its own bitmap that corresponds to the host_id of B. When B next renews its delta lease, it reads the delta leases for all hosts and checks each bitmap to see if its own host_id has been set. It finds the bit for its own host_id set in A's bitmap, and examines its resource request records. (The bit remains set in A's bitmap for set_bitmap_seconds.)

force_mode determines the action the resource lease owner should take:

•

FORCE (1): kill the process holding the resource lease. When the process has exited, the resource lease will be released, and can then be acquired by anyone. The kill signal is SIGKILL (or SIGTERM if SIGKILL is restricted.)

•

GRACEFUL (2): run the program configured by sanlock_killpath against the process holding the resource lease. If no killpath is defined, then FORCE is used.

### Persistent and orphan resource leases
A resource lease can be acquired with the PERSISTENT flag (-P 1). If the process holding the lease exits, the lease will not be released, but kept on an orphan list. Another local process can acquire an orphan lease using the ORPHAN flag (-O 1), or release the orphan lease using the ORPHAN flag (-O 1). All orphan leases can be released by setting the lockspace name (-s lockspace_name) with no resource name.

### Renewal history
sanlock saves a limited history of lease renewal information in each lockspace. See sanlock.conf renewal_history_size to set the amount of history or to disable (set to 0).

IO times are measured in delta lease renewal (each delta lease renewal includes one read and one write).

For each successful renewal, a record is saved that includes:

•

the timestamp written in the delta lease by the renewal

•

the time in milliseconds taken by the delta lease read

•

the time in milliseconds taken by the delta lease write

Also counted and recorded are the number io timeouts and other io errors that occur between successful renewals.

Two consecutive successful renewals would be recorded as:

```
timestamp=5332 read_ms=482 write_ms=5525 next_timeouts=0 next_errors=0
timestamp=5353 read_ms=99 write_ms=3161 next_timeouts=0 next_errors=0
```

Those fields are:

•

timestamp is the value written into the delta lease during that renewal.

•

read_ms/write_ms are the milliseconds taken for the renewal read/write ios.

•

next_timeouts are the number of io timeouts that occurred after the renewal recorded on that line, and before the next successful renewal on the following line.

•

next_errors are the number of io errors (not timeouts) that occurred after renewal recorded on that line, and before the next successful renewal on the following line.

The command 'sanlock client renewal -s lockspace_name' reports the full history of renewals saved by sanlock, which by default is 180 records, about 1 hour of history when using a 20 second renewal interval for a 10 second io timeout.

### Configurable watchdog timeout
Watchdog devices usually have a 60 second timeout, but some devices have a configurable timeout. To use a different watchdog timeout, set sanlock.conf watchdog_fire_timeout (in seconds) to a value supported by the device. The same watchdog_fire_timeout must be configured on all hosts (so all hosts must have watchdog devices that support the same timeout). Unmatching values will invalidate the lease protection provided by the watchdog.

watchdog_fire_timeout and io_timeout should usually be configured together. By default, sanlock uses watchdog_fire_timeout=60 with io_timeout=10. Other combinations to consider are:

watchdog_fire_timeout=30 with io_timeout=5

watchdog_fire_timeout=10 with io_timeout=2

Smaller values make it more likely that a host will be reset by the watchdog while waiting for slow io to complete or for temporary io failures to be resolved. Spurious watchdog resets will also become more likely due to independent, overlapping lockspace outages, each of which would be inconsequential by itself.

## INTERNALS

### Disk Format
•

This example uses 512 byte sectors.

•

Each lockspace is 1MB. It holds 2000 delta_leases, one per sector, supporting up to 2000 hosts.

•

Each paxos_lease is 1MB. It is used as a lease for one resource.

•

The leader_record structure is used differently by each lease type.

•

To display all leader_record fields, see sanlock direct read_leader.

•

A lockspace is often followed on disk by the paxos_leases used within that lockspace, but this layout is not required.

•

The request_record and host_id bitmap are used for requests/events.

•

The mode_block contains the SHARED flag indicating a lease is held in the shared mode.

•

In a lockspace, the host using host_id N writes to a single delta_lease in sector N-1. No other hosts write to this sector. All hosts read all lockspace sectors when renewing their own delta_lease, and are able to monitor renewals of all delta_leases.

•

In a paxos_lease, each host has a dedicated sector it writes to, containing its own paxos_dblock and mode_block structures. Its sector is based on its host_id; host_id 1 writes to the dblock/mode_block in sector 2 of the paxos_lease.

•

The paxos_dblock structures are used by the paxos_lease algorithm, and the result is written to the leader_record.

0x000000 lockspace foo:0:/path:0

(There is no representation on disk of the lockspace in general, only the sequence of specific delta_leases which collectively represent the lockspace.)

delta_lease foo:1:/path:0

```
0x000 0         leader_record         (sector 0, for host_id 1)

                magic: 0x12212010

                space_name: foo

                resource_name: host uuid/name

                ...

                host_id bitmap        (leader_record + 256)
```

delta_lease foo:2:/path:0

```
0x200 512       leader_record         (sector 1, for host_id 2)

                magic: 0x12212010

                space_name: foo

                resource_name: host uuid/name

                ...

                host_id bitmap        (leader_record + 256)
```

delta_lease foo:3:/path:0

```
0x400 1024      leader_record         (sector 2, for host_id 3)

                magic: 0x12212010

                space_name: foo

                resource_name: host uuid/name

                ...

                host_id bitmap        (leader_record + 256)
```

delta_lease foo:2000:/path:0

```
0xF9E00         leader_record         (sector 1999, for host_id 2000)

                magic: 0x12212010

                space_name: foo

                resource_name: host uuid/name

                ...

                host_id bitmap        (leader_record + 256)
```

0x100000 paxos_lease foo:example1:/path:1048576

```
0x000 0         leader_record         (sector 0)

                magic: 0x06152010

                space_name: foo

                resource_name: example1
0x200 512       request_record        (sector 1)

                magic: 0x08292011
0x400 1024      paxos_dblock          (sector 2, for host_id 1)
0x480 1152      mode_block            (paxos_dblock + 128)
0x600 1536      paxos_dblock          (sector 3, for host_id 2)
0x680 1664      mode_block            (paxos_dblock + 128)
0x800 2048      paxos_dblock          (sector 4, for host_id 3)
0x880 2176      mode_block            (paxos_dblock + 128)
0xFA200         paxos_dblock          (sector 2001, for host_id 2000)
0xFA280         mode_block            (paxos_dblock + 128)
```

0x200000 paxos_lease foo:example2:/path:2097152

```
0x000 0         leader_record         (sector 0)

                magic: 0x06152010

                space_name: foo

                resource_name: example2
0x200 512       request_record        (sector 1)

                magic: 0x08292011
0x400 1024      paxos_dblock          (sector 2, for host_id 1)
0x480 1152      mode_block            (paxos_dblock + 128)
0x600 1536      paxos_dblock          (sector 3, for host_id 2)
0x680 1664      mode_block            (paxos_dblock + 128)
0x800 2048      paxos_dblock          (sector 4, for host_id 3)
0x880 2176      mode_block            (paxos_dblock + 128)
0xFA200         paxos_dblock          (sector 2001, for host_id 2000)
0xFA280         mode_block            (paxos_dblock + 128)
```

### Lease ownership
Not shown in the leader_record structures above are the owner_id, owner_generation and timestamp fields. These are the fields that define the lease owner.

The delta_lease at sector N for host_id N+1 has leader_record.owner_id N+1. The leader_record.owner_generation is incremented each time the delta_lease is acquired. When a delta_lease is acquired, the leader_record.timestamp field is set to the time of the host and the leader_record.resource_name is set to the unique name of the host. When the host renews the delta_lease, it writes a new leader_record.timestamp. When a host releases a delta_lease, it writes zero to leader_record.timestamp.

When a host acquires a paxos_lease, it uses the host_id/generation value from the delta_lease it holds in the lockspace. It uses this host_id/generation to identify itself in the paxos_dblock when running the paxos algorithm. The result of the algorithm is the winning host_id/generation - the new owner of the paxos_lease. The winning host_id/generation are written to the paxos_lease leader_record.owner_id and leader_record.owner_generation fields and leader_record.timestamp is set. When a host releases a paxos_lease, it sets leader_record.timestamp to 0.

When a paxos_lease is free (leader_record.timestamp is 0), multiple hosts may attempt to acquire it. The paxos algorithm, using the paxos_dblock structures, will select only one of the hosts as the new owner, and that owner is written in the leader_record. The paxos_lease will no longer be free (non-zero timestamp). Other hosts will see this and will not attempt to acquire the paxos_lease until it is free again.

If a paxos_lease is owned (non-zero timestamp), but the owner has not renewed its delta_lease for a specific length of time, then the owner value in the paxos_lease becomes expired, and other hosts will use the paxos algorithm to acquire the paxos_lease, and set a new owner.

## FILES
/etc/sanlock/sanlock.conf

•

quiet_fail = 1

See -Q

•

debug_renew = 0

See -R

•

logfile_priority = 4

See -L

•

logfile_use_utc = 0

Use UTC instead of local time in log messages.

•

syslog_priority = 3

See -S

•

names_log_priority = 4

Log resource names at this priority level (uses syslog priority numbers). If this is greater than or equal to logfile_priority, each requested resource name and location is recorded in sanlock.log.

•

use_watchdog = 1

See -w

•

high_priority = 1

See -h

•

mlock_level = 1

See -l

•

sh_retries = 8

The number of times to try acquiring a paxos lease when acquiring a shared lease when the paxos lease is held by another host acquiring a shared lease.

•

uname = sanlock

See -U

•

gname = sanlock

See -G

•

our_host_name = <str>

A unique name that a host uses to ensure exclusive ownership of a lockspace host_id (delta lease owner.) The maximum length is 48 characters. If no value is provided in sanlock.conf or on the command line (-e), sanlock attempts to set our_host_name from /sys/devices/virtual/dmi/id/product_uuid. If that is not available, sanlock generates a random uuid to use as our_host_name. Using a fixed our_host_name value will reduce delays when using a lockspace. Using product_uuid will reduce delays further.

•

renewal_read_extend_sec = <seconds>

If a renewal read i/o times out, wait this many additional seconds for that read to complete at the start of the subsequent renewal attempt. When not configured, sanlock waits for an additional io_timeout seconds for a previous timed out read to complete.

•

renewal_history_size = 180

See -H

•

paxos_debug_all = 0

Include all details in the paxos debug logging.

•

debug_io = <str>

Add debug logging for each i/o. "submit" (no quotes) produces debug output at submission time, "complete" produces debug output at completion time, and "submit,complete" (no space) produces both.

•

max_sectors_kb = <str>|<num>

Set to "ignore" (no quotes) to prevent sanlock from checking or changing max_sectors_kb for the lockspace disk when starting a lockspace. Set to "align" (no quotes) to set max_sectors_kb for the lockspace disk to the align size of the lockspace. Set to a number to set a specific number of KB for all lockspace disks.

•

debug_clients = 0

Enable or disable debug logging for all client connections to the sanlock daemon.

•

debug_cmd = +|-<name>

Enable (+name) or disable (-name) debug logging at the command processing level for specifically named commands, e.g. "debug_cmd = +acquire", or "debug_cmd = -inq_lockspace". Repeat this line for each command name. Use a plus prefix before the name to enable and a minus prefix to disable. By default sanlock disables some command level debugging for commands that are often repetitive and fill the in memory debug buffer. This only affects debug logging, not errors or warnings, and disabling command level debugging for a command does not disable lower level debugging for that command. Special values +all and -all can be used to enable or disable all commands, and can be used before or after other debug_cmd lines.

•

write_init_io_timeout = <seconds>

The io timeout to use when initializing ondisk lease structures for a lockspace or resource. This timeout is not used as a part of either lease algorithm (as the standard io_timeout is.)

•

max_worker_threads = <num>

See -t

•

io_timeout = <seconds>

The io timeout for disk operations, most notably delta lease renewals. This value is basis for calculating most other timeout values. (Some special cases may use a different io timeout.) Tune this value with caution, it can substantially alter the overall sanlock behavior.

•

watchdog_fire_timeout = <seconds>

The watchdog device timeout. The watchdog device must support the specified value. It is critical that all hosts use the same value. Not doing so will invalidate the lease protection provided by sanlock. The io_timeout should usually be tuned along with this value, e.g. watchdog_fire_timeout = 30 with io_timeout = 5.

## SEE ALSO
wdmd(8)


wdmd

title: wdmd(8)

summary: watchdog multiplexing daemon

text:
# wdmd(8)

## NAME
wdmd - watchdog multiplexing daemon

## SYNOPSIS
wdmd [OPTIONS]

## DESCRIPTION
This daemon opens /dev/watchdog and allows multiple independent sources to detmermine whether each KEEPALIVE is done. Every test interval (default 10 seconds), the daemon tests each source. If any test fails, the KEEPALIVE is not done. In the default configuration, the watchdog timer will reset the system if no KEEPALIVE is done for 60 seconds ("fire timeout"). This means that if a single test fails 5-6 times in row, the watchdog will fire and reset the system. With multiple test sources, fewer separate failures back to back can also cause a reset, e.g.

T seconds, P pass, F fail

T00: test1 P, test2 P, test3 P: KEEPALIVE done

T10: test1 F, test2 F, test3 P: KEEPALIVE skipped

T20: test1 F, test2 P, test3 P: KEEPALIVE skipped

T30: test1 P, test2 F, test3 P: KEEPALIVE skipped

T40: test1 P, test2 P, test3 F: KEEPALIVE skipped

T50: test1 F, test2 F, test3 P: KEEPALIVE skipped

T60: test1 P, test2 F, test3 P: KEEPALIVE skipped

T60: watchdog fires, system resets

(Depending on timings, the system may be reset sometime shortly before T60, and the tests at T60 would not be run.)

A crucial aspect to the design and function of wdmd is that if any single source does not pass the test for the length of the fire timeout, the watchdog is guaranteed to fire, regardless of whether other sources on the system have passed or failed. A spurious reset due to the combined effects of multiple failing tests as shown above, is an accepted side effect.

The wdmd init script will load the softdog module if no other watchdog module has been loaded.

wdmd cannot be used on the system with any other program that needs to open /dev/watchdog, e.g. watchdog(8).

### Test Source: clients
Using libwdmd, programs connect to wdmd via a unix socket, and send regular messages to wdmd to update an expiry time for their connection. Every test interval, wdmd will check if the expiry time for a connection has been reached. If so, the test for that client fails.

### Test Source: scripts
wdmd will run scripts from a designated directory every test interval. If a script exits with 0, the test is considered a success, otherwise a failure. If a script does not exit by the end of the test interval, it is considered a failure.

## OPTIONS
--version, -V

Print version.

--help, -h

Print usage.

--dump, -d

Print debug information from the daemon.

--probe, -p

Print path of functional watchdog device. Exit code 0 indicates a

functional device was found. Exit code 1 indicates a functional device

was not found.

-D

Enable debugging to stderr and don't fork.

-H 0|1

Enable (1) or disable (0) high priority features such as realtime

scheduling priority and mlockall.

-G name

Group ownership for the socket.

-S 0|1

Enable (1) or disable (0) script tests.

-s path

Path to scripts dir.

-k num

Kill unfinished scripts after num seconds.

-w path

The path to the watchdog device to try first.

--trytimeout, -t seconds

Set the timeout for the watchdog device. Use this to check for supported

timeout values.

--forcefire, -F

Force the watchdog to fire and reset the machine. Use with -t.