About oidentd

Flexible, RFC 1413 compliant Ident daemon with NAT support.

oidentd is a flexible, RFC 1413 compliant Ident server. It runs on Linux, FreeBSD, OpenBSD, NetBSD, and DragonFly BSD. It is highly configurable, allowing the system administrator to define custom responses based on host and port pairs. The administrator can also grant capabilities to individual users to allow them to change their Ident replies, generate random replies, or hide their connections. oidentd supports lookups for NAT connections and is able to forward queries to other servers.

oidentd was originally written by Ryan McCabe in 1998. Since January 2018, it is maintained by Janik Rabe, with contributions from several other volunteers.

The Ident Protocol is used primarily on IRC to detect and prevent abuse and to identify users connecting through shared networks.

Features

  • oidentd is highly configurable, but configuration is optional and sensible defaults are provided.
  • oidentd provides system administrators with a granular, capability-based access control system.
  • Conditional replies enable users to send replies based on connection information, such as ports and IP addresses.
  • oidentd is capable of sending hidden, randomized, and spoofed replies.
  • oidentd can optionally handle requests for NAT connections and is capable of forwarding requests to other Ident servers.
  • Both IPv4 and IPv6 are supported.
  • oidentd is free software licensed under the GNU GPLv2.

Download

Package Managers

Many popular Linux and BSD distributions provide an oidentd package that can be installed with the package manager. On distributions that package the latest version of oidentd, this is normally the recommended approach. Beware that some distributions ship severely outdated versions.

Releases

Releases can be downloaded from files.janikrabe.com. For oidentd, these are source releases (not compiled executables). See the INSTALL file for instructions on how to compile and install oidentd.

Source Code

The source code can be found on GitHub. This is useful if you want to contribute to the project, or if you want to run the latest (unreleased) code. See the HACKING file for information on how to work with the source code.

Getting Started

This chapter describes how to install and configure oidentd.

Installation

Most popular operating system distributions include a recent version of oidentd in their package repositories. Installing oidentd using a package manager is recommended in most cases.

In some cases, however, it may be desirable to install oidentd from source. This may be useful if your distribution does not package a recent version of oidentd, or if there are any compile-time features you would like to enable.

More detailed instructions for compiling and installing oidentd can be found in the INSTALL file included in all releases.

Configuring the Build

After downloading, verifying and extracting oidentd, enter the directory you extracted and run ./configure to configure the build.

On many modern Linux systems, you may have to install libnetfilter_conntrack before running ./configure. More information can be found in the INSTALL file in the source tree.

The ./configure script supports a number of optional flags:

  • --disable-ipv6 disables support for IPv6.
  • --disable-libnfct disables support for libnetfilter_conntrack.
  • --disable-nat disables support for NAT.
  • --disable-debug compiles oidentd without the --debug option to reduce the size of the executable.
  • --enable-warn is intended for developers and enables additional warning messages during compilation.

Compile oidentd

Run make to compile oidentd.

You can run src/oidentd --version to verify that the compilation succeeded.

Install oidentd

Run make install as root to install oidentd.

To uninstall oidentd later on, run make uninstall as root in the same directory.

Capabilities

Capabilities allow the system administrator to control the set of features users have access to. They can be granted or revoked using capability directives. No capabilities are granted to users by default.

forward

The forward capability allows users to forward Ident queries to another server. The host and port arguments specify the host and port of the receiving Ident server. This server must support forwarding (e.g., oidentd with the --proxy option).

Forwarding does not allow users to send replies they otherwise would not be able to send. For example, if the receiving Ident server replies with the name of another user, the reply will be sent back to the client only if the user that owns the connection was granted the spoof and spoof_all capabilities. This restriction does not apply to force forward statements in the system-wide configuration file.

Imperative syntax: forward <host> <port>

hide

The hide capability allows users to hide their connections. When used, oidentd reports a HIDDEN-USER error to clients.

Imperative syntax: hide

numeric

The numeric capability allows users to reply with their user ID (UID) instead of their user name.

Imperative syntax: numeric

random

The random capability allows users to send random alphanumeric Ident replies. Replies are logged so that the system administrator can identify the user responsible for a particular connection.

Imperative syntax: random

random_numeric

The random_numeric capability allows users to send random numeric Ident replies of the form userNNNNN, where N represents a digit from 0 to 9. Replies are logged so that the system administrator can identify the user responsible for a particular connection.

Imperative syntax: random_numeric

reply

The reply capability cannot be granted or revoked. However, using it may require one or more of spoof, spoof_all, and spoof_privport, depending on the replies and type of connection.

If more than one reply is given, a random reply is chosen from the list for each incoming query. At least one reply must be specified.

Imperative syntax: reply <replies ...>

spoof

The spoof capability allows users to send custom Ident replies, except in cases that require the spoof_all or spoof_privport capabilities.

This capability does not have an imperative syntax.

spoof_all

The spoof_all capability allows users to reply with the names of other users on the system. It only works in conjunction with the spoof capability.

This capability does not have an imperative syntax.

spoof_privport

The spoof_privport capability allows users to spoof replies for connections to privileged foreign ports (port numbers below 1024). It only works in conjunction with the spoof capability.

This capability does not have an imperative syntax.

Configuration

When an Ident query is received, oidentd normally replies with the user name of the user that owns the corresponding connection. Users can override this behavior only if they have been granted permission to do so through the system-wide configuration file.

System-wide Configuration File

The system-wide configuration file is usually found at /etc/oidentd.conf or /usr/local/etc/oidentd.conf, depending on how oidentd was installed. It is not necessary for this file to exist.

This file may contain any number of user directives.

User Configuration File

Each user may also create a user configuration file at ~/.config/oidentd.conf or ~/.oidentd.conf. If both files exist, only the former is used. The user configuration file is ignored if oidentd does not have permission to read it.

This file may contain one directive of the following form:

global {
	<capability-statements ...>
}

This global directive matches all connections. If used, it should be the first directive in the file.

The user configuration file may also contain any number of directives of the following form:

<range-specification> {
	<capability-statements ...>
}

In this form the directive only applies to connections that match the given range specification.

User Directives

A user directive takes one of the following forms:

default {
	<range-directives ...>
}

This form can be used to specify defaults for users. There should be no more than one directive of this form. If used, it should be the first user directive.

user "<username>" {
	<range-directives ...>
}

In this form the directive applies only to the specified user.

Range Directives

A range directive takes one of the following forms:

default {
	<capability-directives ...>
}

In this form the directive matches when no other range directive in its scope does. There should be no more than one directive of this form. If used, it should be the first range directive.

<range-specification> {
	<capability-directives ...>
}

In this form the directive only applies to connections that match the given range specification.

Range Specification

A range specification takes the following form:

[to <host>] [fport <port>] [from <host>] [lport <port>]
  • to is the foreign address associated with the connection.
  • fport is the foreign port associated with the connection.
  • from is the local address associated with the connection.
  • lport is the local port associated with the connection.

At least one of the four filters must be specified.

Hosts may be specified by hostname or by IP address. Ports may optionally be specified as a port range of the form min:max, min:, or :max.

A range specification matches a connection if all specified filters match.

Capability Directives

A capability directive takes one of the following forms:

allow <capability>

In this form the directive grants the specified capability.

deny <capability>

In this form the directive revokes the specified capability.

force <capability-statement>

In this form the directive enforces use of the specified capability.

Capabilities

The following are valid capabilities:

Capability Statements

The following are valid capability statements:

Further Reading

The oidentd.conf(5) manual page contains further information on how to configure oidentd, as well as detailed descriptions of all capabilities.

Examples

The following examples illustrate how capabilities and conditional directives can be used in system-wide and user configuration files.

Lines stating with # are comments. They are ignored by oidentd.

System-wide Configuration File

This configuration allows ryan to send spoofed and random Ident replies, except in response to lookups for connections to example.net. Other users' connections are hidden so that no user information is disclosed.

default {  # User defaults
	default {  # Connection defaults
		# Hide all connections from users not
		# explicitly listed in this file.
		force hide
	}
}

user ryan {  # Settings for user "ryan"

	default {  # Connection defaults
		# Allow ryan to send custom Ident replies,
		# except for the names of other users.
		allow spoof

		# Allow ryan to send random Ident replies.
		allow random
	}

	to example.net {  # Connections to example.net
		# Do not allow ryan to spoof Ident replies.
		force reply "ryan"
	}
}

User Configuration File

This user configuration file instructs oidentd to reply to Ident queries for connections to foreign ports 6667 through 6697 with the name of a random Greek letter. This requires the spoof capability. It also requires the spoof_all capability if there is a local user named "alpha", "beta", or "gamma".

A random alphanumeric Ident reply is sent in response to all other queries. This requires the random capability.

global {  # Connection defaults
	# Send random Ident replies by default.
	random
}

fport 6667:6697 {  # Foreign ports from 6667 to 6697
	# Choose one of three Greek letters at random.
	reply "alpha" "beta" "gamma"
}

Starting the Server

oidentd can be run as a standalone server or started by a service manager. By default, oidentd forks to the background after starting up.

If you installed oidentd from your distribution's package repositories, an initialization script or systemd service may already have been included in the package. Consult your distribution's documentation for more information.

oidentd needs to be started as root on most systems, but normally drops its privileges automatically after starting up. See Dropping Privileges for details.

Run oidentd to start the server.

oidentd accepts a large number of command-line options. Some commonly used options are:

  • -a, --address: bind to the specified address (may be specified multiple times)
  • -d, --debug: show messages that may be useful for debugging
  • -i, --foreground: do not run as a background process
  • -p, --port: listen on the specified port instead of port 113

The oidentd(8) manual page contains a complete list of options with detailed explanations. oidentd --help prints a list with more concise descriptions.

systemd Service

Many systemd-based distributions include service files for oidentd. On these distributions, oidentd can be started and enabled with the following command:

systemctl enable --now oidentd

Support

If you need help or have any questions about oidentd, feel free to use any of the following resources.

Documentation

Documentation for oidentd can be found in the oidentd(8), oidentd.conf(5), and oidentd_masq.conf(5) manual pages.

Additional documentation for developers and package maintainers is available in the INSTALL and HACKING files in the oidentd source tree.

IRC Channel

You can find us in #oidentd on ircs://irc.libera.chat. Please be patient; it may take a while for someone to see your message.

Contact the Maintainer

Feel free to contact the project maintainer if you have any questions or need help with oidentd.

This is also the best way to share any feedback you may have. We're always looking for ways to make oidentd better, and we'd appreciate your help.

Guides

The guides in this chapter are intended to serve as a starting point when configuring oidentd to work with other software.

Using oidentd with Quassel

You can use oidentd to spoof Ident replies so that they match Idents configured within Quassel.

Forwarding to Quassel

oidentd can forward incoming queries for connections owned by the Quassel user directly to Quassel's built-in Ident server. This is the recommended method.

Append the following to your system-wide configuration file:

user "<username>" {
	default {
		allow spoof

		# Add the next line if Quassel needs to
		# reply with the name of a local user.
		allow spoof_all

		force forward <host> <port>
	}
}

Replace <username> with the user name of the Quassel user (e.g., quasselcore).

Replace <host> with the IP address or hostname Quassel's built-in Ident server is configured to listen on (e.g., ::1).

Replace <port> with the port Quassel's built-in Ident server is configured to listen on (e.g., 10113).

Using Quassel's oidentd Configuration Generator

Quassel can automatically write to an oidentd user configuration file when establishing a new connection.

Use of this feature is discouraged as of oidentd 2.3.0. Some IRC servers send Ident queries before the connection's local port is known to Quassel, which may cause lookups to fail.

Append the following to your system-wide configuration file:

user "<username>" {
	default {
		allow spoof

		# Use this only if Quassel needs to spoof local user names
		allow spoof_all
	}
}

Replace <username> with the user name of the Quassel user (e.g., quasselcore).

Ensure that the Quassel home directory (typically ~quasselcore) is world-executable (mode 0711) so that oidentd can read the user configuration file:

chmod 0711 ~quasselcore

Finally, make sure Quassel is run with the --oidentd flag.

Your changes will take effect after you reload oidentd and restart Quassel.

Using oidentd with ZNC

You can use oidentd to spoof Ident replies so that they match Idents configured within ZNC.

Append the following to your system-wide configuration file:

user "<username>" {
	default {
		allow spoof

		# Add the next line if ZNC needs to
		# reply with the name of a local user.
		allow spoof_all
	}
}

Replace <username> with the user name of the ZNC user (e.g., znc).

Change to the user running ZNC (e.g., using su znc -ls "$SHELL"), and use the following commands to create an empty user configuration file:

touch ~/.oidentd.conf
chmod 0644 ~/.oidentd.conf

Ensure that the ZNC home directory (typically ~znc) is world-executable (mode 0711) so that oidentd can read the user configuration file:

chmod 0711 ~

Ensure that ZNC's identfile module is loaded and configured correctly:

/MSG *status LoadMod identfile
/MSG *identfile SetFile ~/.oidentd.conf
/MSG *identfile SetFormat global { reply "%user%" }
/MSG *status SaveConfig

Note that %user% expands to the name of the ZNC user that initiated the connection. Another popular choice is %ident%, which allows users to specify any Ident.

Your changes will take effect after you reload oidentd and reconnect to IRC.

NAT

This chapter explains how to use oidentd for NAT connections.

Introduction

oidentd can handle Ident queries for other machines connecting through the server it is running on. This is especially useful when the server running oidentd performs Network Address Translation (NAT).

Before configuring oidentd to use NAT, please take a look at the KERNEL_SUPPORT.md file in the source tree to find out whether NAT is supported on your system.

oidentd supports two features that may be useful in combination with NAT:

  • Static replies instruct oidentd to send a certain reply in response to every Ident query intended for a particular host or subnetwork.
  • Forwarding allows Ident queries to be forwarded through NAT to the host that established a connection.

Static Replies

oidentd can send different Ident replies for each host connecting through the machine it is running on.

To enable this functionality, oidentd must be run with the --masquerade (-m) flag.

Configuring Replies

Replies can be configured in the masquerading configuration file, which is usually found in /etc/oidentd_masq.conf or in /usr/local/etc/oidentd_masq.conf, depending on how oidentd was installed.

This file should consist of lines of the following form:

<host>[/subnet] ident_reply system_type

The masquerading configuration file is read from top to bottom, so more specific rules should be placed before more general ones. For example:

10.0.0.1     user1  UNIX
10.0.0.2     user2  FREEBSD
10.0.0.0/24  user3  OTHER

In this example, a user1 reply is sent in response to all requests for 10.0.0.1. A user2 reply is sent for all requests for 10.0.0.2. Finally, user3 is sent in response to requests for other machines in the 10.0.0.0/24 subnetwork.

Detailed information can be found in the oidentd_masq.conf(5) manual page.

Forwarding

oidentd can forward Ident queries to the host they were intended for, provided that this host is connecting through the machine oidentd is running on.

When forwarding is enabled, the default behavior is to forward immediately and only fall back to using the configured static replies if forwarding fails. This can be changed by using the --masquerade-first (-M) flag, in which case oidentd only forwards requests if no matching static reply was found.

Configuring the Gateway

Forwarding can be enabled on the device performing network address translation by running oidentd with the --forward (-f) option. Optionally, a target port may be specified using --forward=port. If no port is specified, port 113 is used.

Configuring the Servers

All machines that need to receive forwarded queries must be running an Ident server capable of handling these queries, such as oidentd with the --proxy (-P) option. For example, oidentd can be run on a machine behind NAT with the following command:

oidentd -P 10.0.0.1

This allows 10.0.0.1 to forward queries to the current oidentd instance.

If you specified a custom target port for forwarding, make sure the target server is configured to listen on that port:

oidentd -P 10.0.0.1 -p 113

Port 113 is the default and does not need to be specified explicitly.

Security

This chapter covers security concerns related to Ident servers and provides advice for mitigating possible risks.

Dropping Privileges

It is highly recommended not to run internet-facing services as root. For this reason, oidentd attempts to switch to an unprivileged user automatically after starting up.

Please note that oidentd needs to run as root on a small number of systems. On these systems, a warning is printed at startup and privileges are not dropped automatically. Your system is affected by this limitation if oidentd --version prints "Needs root access: Yes".

Default User

By default, oidentd attempts to run as one of the following users, in order of preference. If a user does not exist, oidentd tries to use the next one.

  • oidentd
  • nobody

If neither of the above users exists, oidentd switches to user ID 65534.

Default Group

By default, oidentd attempts to run as one of the following groups, in order of preference. If a group does not exist, oidentd tries to use the next one.

  • oidentd
  • nobody
  • nogroup

If none of the above groups exist, oidentd switches to group ID 65534.

Changing This Behavior

The --user and --group options can be used to run oidentd as another user or group. oidentd refuses to start up if the user or group specified by either of these options does not exist, or if privileges cannot be dropped for some other reason.

Hiding Connections

It is recommended to hide connections to any servers running on your machine to avoid disclosing unnecessary information.

The recommended way to accomplish this is to hide all connections and only respond to queries for certain user accounts:

default {
	default {
		force hide
	}
}

user "ryan" {
	default {
		force reply "ryan"
	}
}

It is also possible to hide individual users' connections:

user "root" {
	default {
		force hide
	}
}

user "http" {
	default {
		force hide
	}
}

Alternatively, the random and random_numeric capabilities may be used to conceal users' real login names while still allowing the system administrator to identify who was responsible for a particular connection. See the list of capabilities for more information.

Identification vs. Authentication

The Ident protocol was designed for identification, not authentication. Please don't use it for access control.

The primary purpose of the Ident protocol is to serve as an auditing and abuse prevention mechanism. For example, many IRC servers act as Ident clients, querying and publicly displaying users' Ident replies. This allows providers of IRC bouncers, shell accounts and other services to identify users abusing their systems and enables channel operators and network operators to remove individual users without excluding their entire host or network.

Ident queries and replies are sent as plain text, with no encryption or authentication, and can be intercepted or modified by an attacker. In addition, it is not possible to prevent compromised or malicious hosts from sending arbitrary Ident replies. For these reasons, the Ident protocol is not suitable for authentication or access control.