libexec/identd/identd.8

   1 .\" $NetBSD: identd.8,v 1.19 2005/04/03 22:15:32 peter Exp $
   2 .\"
   3 .\" This software is in the public domain.
   4 .\" Written by Peter Postma <peter@NetBSD.org>
   5 .\"
   6 .Dd April 4, 2005
   7 .Dt IDENTD 8
   8 .Os
   9 .Sh NAME
  10 .Nm identd
  11 .Nd TCP/IP Ident protocol server
  12 .Sh SYNOPSIS
  13 .Nm
  14 .Op Fl 46beIilNnr
  15 .Op Fl a Ar address
  16 .Op Fl c Ar charset
  17 .Op Fl F Ar format
  18 .Op Fl f Ar username
  19 .Op Fl g Ar uid
  20 .Op Fl L Ar username
  21 .Op Fl m Ar filter
  22 .Op Fl o Ar osname
  23 .Op Fl P Ar address
  24 .Op Fl p Ar portno
  25 .Op Fl t Ar seconds
  26 .Op Fl u Ar uid
  27 .Sh DESCRIPTION
  28 .Nm
  29 is a TCP/IP server which implements the user identification protocol
  30 as specified in RFC 1413.
  31 .Pp
  32 .Nm
  33 operates by looking up specific TCP/IP connections and returning
  34 information which may or may not be associated with the process owning
  35 the connection.
  36 .Pp
  37 The following options are available:
  38 .Bl -tag -width XXusernameXX
  39 .It Fl 4
  40 Bind to IPv4 addresses only
  41 (valid with flag
  42 .Fl b ) .
  43 .It Fl 6
  44 Bind to IPv6 addresses only
  45 (valid with flag
  46 .Fl b ) .
  47 .It Fl a Ar address
  48 Bind to the specified
  49 .Ar address .
  50 This may be an IPv4 or IPv6 address or even a hostname.
  51 If a hostname is specified then
  52 .Nm
  53 will resolve it to an address (or addresses) and will bind this address
  54 (valid with flag
  55 .Fl b ) .
  56 .It Fl b
  57 Run in the background (as daemon).
  58 .It Fl c Ar charset
  59 Specify an optional character set designator to be included in replies.
  60 .Ar charset
  61 should be a valid charset set as described in the
  62 .Tn MIME RFC
  63 in upper case characters.
  64 .It Fl e
  65 Return
  66 .Dq UNKNOWN-ERROR
  67 instead of the usual
  68 .Dq NO-USER
  69 or
  70 .Dq INVALID-PORT
  71 error replies.
  72 .It Fl F Ar format
  73 Specify the format to display info.
  74 The allowed format specifiers are:
  75 .Bd -literal
  76 %u      print user name
  77 %U      print user number
  78 %g      print (primary) group name
  79 %G      print (primary) group number
  80 %l      print list of all groups by name
  81 %L      print list of all groups by number
  82 .Ed
  83 .Pp
  84 The lists of groups (%l, %L) are comma-separated, and start with the primary
  85 group which is not repeated.
  86 Any other characters (preceded by %, and those not preceded by it)
  87 are printed literally.
  88 .It Fl f Ar username
  89 Specify a fall back
  90 .Ar username .
  91 If the lookup fails then this username will be returned.
  92 This can be useful for when running this service on a NAT host and
  93 not using the forward/proxy functionality.
  94 .It Fl g Ar gid
  95 Specify the group id number or name which the server should switch to after
  96 binding itself to the TCP/IP port.
  97 .It Fl I
  98 Same as
  99 .Fl i
 100 but without the restriction that the username in
 101 .Pa .ident
 102 must not match an existing user.
 103 .It Fl i
 104 If the
 105 .Pa .ident
 106 file exists in the home directory of the identified user, return the username
 107 found in that file instead of the real username.
 108 If the username found in
 109 .Pa .ident
 110 is that of an existing user, then the real username will be returned.
 111 .It Fl L Ar username
 112 Specify a
 113 .Dq lie
 114 .Ar username .
 115 .Nm
 116 will return this name for all valid ident requests.
 117 .It Fl l
 118 Use
 119 .Xr syslogd 8
 120 for logging purposes.
 121 .It Fl m Ar filter
 122 Enables forwarding of ident queries.
 123 The
 124 .Ar filter
 125 argument specifies which packet filter should be used to lookup the
 126 connections, currently
 127 .Sq pf
 128 and
 129 .Sq ipfilter
 130 are supported packet filters.
 131 Note that
 132 .Nm
 133 changes the ident queries to use the local port on the NAT host instead of
 134 the local port on the forwarding host.
 135 This is needed because otherwise we can't do a lookup on the proxy host.
 136 On the proxy host,
 137 .Dq proxy mode
 138 should be enabled with the
 139 .Fl P
 140 flag or
 141 .Dq lying mode
 142 with the
 143 .Fl L
 144 flag.
 145 .It Fl N
 146 Enable
 147 .Pa .noident
 148 files.
 149 If this file exists in the home directory of the identified user then return
 150 .Dq HIDDEN-USER
 151 instead of the normal USERID response.
 152 .It Fl n
 153 Return numeric user IDs instead of usernames.
 154 .It Fl o Ar osname
 155 Return
 156 .Ar osname
 157 instead of the default
 158 .Dq UNIX .
 159 .It Fl P Ar address
 160 Specify a proxy server which will be used to receive proxied ident
 161 queries from.
 162 See also the
 163 .Fl m
 164 flag how this operates.
 165 .It Fl p Ar portno
 166 Specify an alternative port number under which the server should run.
 167 The default is port 113
 168 (valid with flag
 169 .Fl b ) .
 170 .It Fl r
 171 Return a random name of alphanumeric characters.
 172 If the
 173 .Fl n
 174 flag is also enabled then a random number will be returned.
 175 .It Fl t Ar seconds
 176 Specify a timeout for the service.
 177 The default timeout is 30 seconds.
 178 .It Fl u Ar uid
 179 Specify the user id number or name to which the server should switch after
 180 binding itself to the TCP/IP port.
 181 .El
 182 .Sh FILES
 183 .Pa /etc/inetd.conf
 184 .Sh EXAMPLES
 185 .Nm
 186 operates from
 187 .Xr inetd 8
 188 or as standalone daemon.
 189 Put the following lines into
 190 .Xr inetd.conf 5
 191 to enable
 192 .Nm
 193 as an IPv4 and IPv6 service via inetd:
 194 .Pp
 195 ident stream tcp nowait nobody /usr/libexec/identd identd -l
 196 .Pp
 197 ident stream tcp6 nowait nobody /usr/libexec/identd identd -l
 198 .Pp
 199 To run
 200 .Nm
 201 as standalone daemon, use the
 202 .Fl b
 203 flag.
 204 .Sh SEE ALSO
 205 .Xr inetd.conf 5 ,
 206 .Xr inetd 8
 207 .Sh AUTHORS
 208 This implementation of
 209 .Nm
 210 is written by
 211 .An Peter Postma
 212 .Aq peter@NetBSD.org .
 213 .Sh CAVEATS
 214 Since
 215 .Nm
 216 should typically not be run as a privileged user or group,
 217 .Pa .ident
 218 files for use when running with the
 219 .Fl I
 220 or
 221 .Fl i
 222 flags will need to be world accessible.
 223 The same applies for
 224 .Pa .noident
 225 files when running with the
 226 .Fl N
 227 flag.
 228 .Pp
 229 When forwarding is enabled with the
 230 .Fl m
 231 flag then
 232 .Nm
 233 will need access to either
 234 .Pa /etc/pf
 235 (pf) or
 236 .Pa /etc/ipnat
 237 (ipfilter).
 238 Since it's not a good idea to run
 239 .Nm
 240 under root, you'll need to adjust group owner/permissions to the device(s)
 241 and run
 242 .Nm
 243 under that group.