OIDENTD.CONF(5) oidentd User Manual OIDENTD.CONF(5)
NAME
oidentd.conf - oidentd configuration files
DESCRIPTION
The oidentd configuration files are used to control the responses
oidentd sends to clients after receiving a query for a connection owned
by a particular user.
The system-wide configuration file /etc/oidentd.conf specifies the types
of responses individual users are permitted to send. By default, users
must respond with their real username.
The user configuration files ~/.config/oidentd.conf allow users to send
custom Ident responses or to hide their identities, provided that they
have been granted the necessary capabilities through the system-wide
configuration file. If this file does not exist or oidentd was compiled
without XDG Base Directory support, the file ~/.oidentd.conf is used
instead. Note that user configuration files are read only after a
connection is determined to belong to the user in question.
SYSTEM-WIDE CONFIGURATION FILE
The system-wide configuration file is used to grant capabilities to
users or force users to use a certain capability. The default behavior
is not to grant any privileges, which means that all users must send
their real usernames in response to Ident queries. The system-wide
configuration file may be empty or missing, in which case this default
applies. Changes to this file take effect only after oidentd is reloaded
(which occurs when a SIGHUP signal is received) or restarted.
The system-wide configuration file contains zero or one directive of the
following form:
default {
range-directives...
}
This default directive matches all users for which no explicit rules
have been defined. Any user directives following this directive inherit
the capabilities it defines. If present, the default directive should be
the first directive in the user configuration file.
The system-wide configuration file may also contain zero or more
directives of the following form:
user username {
range-directives...
}
This user directive applies only to the specified user.
USER CONFIGURATION FILE
Each user may create a user configuration file at ~/.config/oidentd.conf
or ~/.oidentd.conf. This file must be readable by the user oidentd runs
as. The user configuration file is read automatically after every
successful lookup, so any changes take effect immediately.
The user configuration file contains zero or one directive of the
following form:
global {
capability-statements...
}
This global directive matches all connections owned by the user. If
present, it should be the first directive in the user configuration
file.
The user configuration file may also contain zero or more directives of
the following form:
range-specification {
capability-statements...
}
This range directive applies only to connections that match the given
range specification.
RANGE DIRECTIVES
At most one range directive in any given scope may take the following
form:
default {
capability-directives...
}
This default directive defines rules for all connections that do not
match any other range directive. If present, the default directive
should be the first directive in its scope.
A range directive may also take the following form:
range-specification {
capability-directives...
}
This range directive applies only to connections that match the given
range specification.
RANGE SPECIFICATIONS
A range specification consists of filters that define which connections
a range directive applies to. It takes the following form:
to fhost fport fport from lhost lport lport
This range specification matches only connections with the specified
foreign host, foreign port, local host, and local port. At least one of
these filters must be specified. Omitted filters match any value.
Filters may be specified in any order.
The fhost filter specifies the foreign host or address of a connection,
from the perspective of the machine running oidentd.
The fport filter specifies the foreign port or port range of a
connection.
The lhost filter specifies the local host or address of a connection,
from the perspective of the machine running oidentd. This may be useful
for supporting virtual hosts on systems with more than one IP address.
The lport filter specifies the local port or port range of a connection.
Ports can be specified either numerically (e.g., 113) or using a service
name (e.g., ident). Port ranges are specified numerically as min:max.
The min port may be omitted to select all ports less than or equal to
the max port. Likewise, the max port may be omitted to select all ports
greater than or equal to the min port.
CAPABILITY DIRECTIVES
A capability directive may take one of the following forms:
allow capability
In this form, the directive grants the user permission to use the
specified capability.
deny capability
In this form, the directive revokes the user’s permission to use the
specified capability.
force capability-statement
In this form, the directive forces the user to use the specified
capability.
CAPABILITIES
The following expressions are valid capabilities:
forward
hide
numeric
random
random_numeric
These capabilities allow users to use the corresponding capability
statements.
spoof
The spoof capability allows users to send custom Ident replies. Note
that this does not include replying with the name of another user or
spoofing replies for connections to privileged foreign ports.
spoof_all
The spoof_all capability allows users to reply with the names of other
users. This capability should be used with care, as it allows users to
impersonate other users on the local system. The spoof_all capability
only works in conjunction with spoof, but does not imply it.
spoof_privport
The spoof_privport capability allows users to spoof replies for
connections to privileged foreign ports (with port numbers below 1024).
The spoof_privport capability only works in conjunction with spoof, but
does not imply it.
CAPABILITY STATEMENTS
A capability statement may take one of the following forms:
forward host port
Forward received queries to another Ident server. The target server must
support forwarding (like oidentd with the --proxy option).
Additional capabilities may be required for forwarding to succeed. For
example, the spoof capability is required if the target server sends a
response other than the user’s name on the forwarding server. It may
therefore be desirable to also grant at least one of hide, spoof,
spoof_all, and spoof_privport in addition to the forward capability. If
force forward is used, no additional checks are performed and no
capabilities are required.
If forwarding fails, oidentd responds with a "HIDDEN-USER" error or with
the user’s real username, depending on whether the user has been granted
the hide capability. Replies are logged, allowing the system
administrator to identify which user sent a particular reply.
hide
Hide Ident replies from clients. When this capability is used, oidentd
reports a "HIDDEN-USER" error to Ident clients instead of sending an
Ident reply.
numeric
Respond with the user ID (UID).
random
Send randomly generated, alphanumeric Ident replies. A new reply is
generated for each Ident lookup. Replies are logged, allowing the system
administrator to identify which user sent a particular reply.
random_numeric
Send randomly generated, numeric Ident replies between 0 (inclusive) and
100,000 (exclusive), prefixed with "user". A new reply is generated for
each Ident lookup. Replies are logged, allowing the system administrator
to identify which user sent a particular reply.
reply reply1 [reply2 ...]
Send an Ident reply chosen at random from the given list of quoted
replies. When used in a user configuration file, at most 20 replies may
be specified. In the system-wide configuration file, up to 255 replies
may be specified. Replies are logged, allowing the system administrator
to identify which user sent a particular reply.
EXAMPLES
SYSTEM-WIDE CONFIGURATION FILE
default {
default {
allow spoof
}
fport 6667 {
deny spoof
allow hide
}
}
Allow all users to spoof Ident replies, except on connections to port
6667. Only on connections to port 6667, allow users to hide their Ident
replies.
user "root" {
default {
force hide
}
}
Hide all connections owned by the root user.
user "lisa" {
lport 1024: {
force reply "me"
}
}
For connections owned by user "lisa" on local port 1024 or greater,
always reply with "me", ignoring any settings in the user configuration
file.
USER CONFIGURATION FILE
global {
reply "paul"
}
Reply with "paul" to all Ident queries.
to irc.example.net fport 6667 {
hide
}
Hide Ident replies for connections to irc.example.net on port 6667.
STRING FORMATTING
Strings may be enclosed in double quotes. This is useful for strings
containing special characters that would otherwise be interpreted in an
unintended way.
Quoted strings may contain the following escape sequences:
\a alert (bell)
\b backspace
\f form feed
\n newline (line feed)
\r carriage return
\t horizontal tab
\v vertical tab
\\:\ backslash
\" double quotation mark
\\:NNN the character with octal numerical value NNN
\xNN the character with hexadecimal numerical value NN
COMMENTS
After encountering a number sign ("#"), oidentd ignores any remaining
text on the same line. This allows users to add comments to the
configuration file. Comments can also be written in the following form,
which allows them to span multiple lines:
/* comment */
AUTHOR
Janik Rabe <info@janikrabe.com>
https://janikrabe.com
Originally written by Ryan McCabe.
BUGS
Please report any bugs to Janik Rabe <info@janikrabe.com>.
SEE ALSO
oidentd(8) oidentd_masq.conf(5)
oidentd 3.1.0 OIDENTD.CONF(5)
Generated by dwww version 1.16 on Tue Dec 16 07:51:33 CET 2025.