1 '\" te
   2 .\"  Copyright (c) 1992-1996 Competitive Automation, Inc.
   3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" Copyright (c) 2020 Peter Tribble
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   6 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
   7 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH DHCPINFO 1 "Feb 13, 2020"
   9 .SH NAME
  10 dhcpinfo \- display values of parameters received through DHCP
  11 .SH SYNOPSIS
  12 .nf
  13 \fBdhcpinfo\fR [\fB-c\fR] [\fB-i\fR \fIinterface\fR] [\fB-n\fR \fIlimit\fR] [\fB-v 4|6\fR] \fIcode\fR
  14 .fi
  15 
  16 .LP
  17 .nf
  18 \fBdhcpinfo\fR [\fB-c\fR] [\fB-i\fR \fIinterface\fR] [\fB-n\fR \fIlimit\fR] [\fB-v 4|6\fR] \fIidentifier\fR
  19 .fi
  20 
  21 .SH DESCRIPTION
  22 The \fBdhcpinfo\fR utility prints the \fBDHCP\fR-supplied value(s) of the
  23 parameter requested on the command line. The parameter can be identified either
  24 by its numeric code in the \fBDHCP\fR specification, or by its mnemonic
  25 identifier, as listed in \fBdhcp_inittab\fR(4). This command is intended to be
  26 used in command substitutions in the shell scripts invoked at system boot or
  27 in event scripts as described in \fBdhcpagent\fR(1M). It first contacts the
  28 DHCP client daemon \fBdhcpagent\fR(1M) to verify that \fBDHCP\fR has
  29 successfully completed on the requested interface. If \fBDHCP\fR has
  30 successfully completed on the requested interface, \fBdhcpinfo\fR retrieves the
  31 values for the requested parameter. Parameter values echoed by \fBdhcpinfo\fR
  32 should not be used without checking its exit status. See \fBexit\fR(1).
  33 .sp
  34 .LP
  35 See \fBdhcp_inittab\fR(4) for the list of mnemonic identifier codes for all
  36 \fBDHCP\fR parameters. See \fIRFC 2132, DHCP Options and BOOTP Vendor
  37 Extensions\fR for more details on DHCPv4 parameters, and RFC 3315, Dynamic Host
  38 Configuration Protocol for IPv6 (DHCPv6), for more details on DHCPv6
  39 parameters.
  40 .SS "Output Format"
  41 The output from \fBdhcpinfo\fR consists of one or more lines of \fBASCII\fR
  42 text; the format of the output depends upon the requested parameter. The number
  43 of values returned per line and the total number of lines output for a given
  44 parameter are determined by the parameter's \fBgranularity\fR and \fBmaximum\fR
  45 values, respectively, as defined by \fBdhcp_inittab\fR(4).
  46 .sp
  47 .LP
  48 The format of each individual value is determined by the data type of the
  49 option, as determined by \fBdhcp_inittab\fR(4). The possible data types and
  50 their formats are listed below:
  51 .sp
  52 
  53 .sp
  54 .TS
  55 c c c
  56 l l l .
  57 Data Type       Format  \fBdhcp_inittab\fR(4) type
  58 Unsigned Number One or more decimal digits      T{
  59 \fBUNUMBER8\fR, \fBUNUMBER16\fR, \fBUNUMBER32\fR, \fBUNUMBER64\fR
  60 T}
  61 Signed Number   T{
  62 One or more decimal digits, optionally preceded by a minus sign
  63 T}      T{
  64 \fBSNUMBER8\fR, \fBSNUMBER16\fR, \fBSNUMBER32\fR, \fBSNUMBER64\fR
  65 T}
  66 \fBIP\fR Address        Dotted-decimal notation \fBIP\fR
  67 IPv6 Address    Colon-separated notation        \fBIPv6\fR
  68 Octet   T{
  69 The string \fB0x\fR followed by a two-digit hexadecimal value
  70 T}      \fBOCTET\fR
  71 String  Zero or more \fBASCII\fR characters     \fBASCII\fR
  72 DUID    DHCP Unique Identifier text     \fBDUID\fR
  73 Domain Name     T{
  74 Standard dot-separated domain name, RFC 1035 format
  75 T}      \fBDOMAIN\fR
  76 .TE
  77 
  78 .SH OPTIONS
  79 The following options are supported:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB-c\fR\fR
  84 .ad
  85 .RS 16n
  86 Displays the output in a canonical format. This format is identical to the
  87 \fBOCTET\fR format with a granularity of \fB1\fR.
  88 .RE
  89 
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fB-i\fR \fIinterface\fR\fR
  94 .ad
  95 .RS 16n
  96 Specifies the interface to retrieve values for \fBDHCP\fR parameters from. If
  97 this option is not specified, the primary interface is used.
  98 .sp
  99 If a primary interface has not been selected for the system by
 100 \fBifconfig\fR(1M) or for this command by \fB-i\fR, the system automatically
 101 selects an interface to consider as primary for the current command invocation.
 102 The selection chooses the interface whose name sorts lexically first, and that
 103 has DHCP parameters attached.  This selection does not affect system state. Use
 104 \fBifconfig\fR(1M) to set a primary interface.
 105 .sp
 106 The recommended practice in the \fBdhcpagent\fR(1M) \fBeventhook\fR scripts is
 107 to specify the desired interface with \fB-i\fR, rather than relying on primary
 108 selection.
 109 .sp
 110 For DHCPv6, the interface name used should be the name of the physical
 111 interface, not one of the logical interfaces created by \fBdhcpagent\fR.
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB-n\fR \fIlimit\fR\fR
 118 .ad
 119 .RS 16n
 120 Limits the list of values displayed to \fIlimit\fR lines.
 121 .RE
 122 
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fB-v 4|6\fR\fR
 127 .ad
 128 .RS 16n
 129 Specifies the DHCP version to query. Use \fB-v 4\fR for DHCPv4 and \fB-v 6\fR
 130 for DHCPv6.
 131 .RE
 132 
 133 .SH OPERANDS
 134 The following operands are supported:
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fIcode\fR\fR
 139 .ad
 140 .RS 14n
 141 Numeric code for the requested \fBDHCP\fR parameter, as defined by the
 142 \fBDHCP\fR specification. Vendor options are specified by adding \fB256\fR to
 143 the actual vendor code for DHCPv4, and \fB65536\fR for DHCPv6.
 144 .RE
 145 
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fIidentifier\fR\fR
 150 .ad
 151 .RS 14n
 152 Mnemonic symbol for the requested \fBDHCP\fR parameter, as listed in
 153 \fBdhcp_inittab\fR(4).
 154 .RE
 155 
 156 .SH EXIT STATUS
 157 The following exit values are returned:
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fB0\fR\fR
 162 .ad
 163 .RS 5n
 164 Successful operation.
 165 .RE
 166 
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fB2\fR\fR
 171 .ad
 172 .RS 5n
 173 The operation was not successful. The \fBDHCP\fR client daemon might not be
 174 running, the interface might have failed to configure, or no satisfactory
 175 \fBDHCP\fR responses were received.
 176 .RE
 177 
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fB3\fR\fR
 182 .ad
 183 .RS 5n
 184 Bad arguments.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fB4\fR\fR
 191 .ad
 192 .RS 5n
 193 The operation timed out.
 194 .RE
 195 
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fB6\fR\fR
 200 .ad
 201 .RS 5n
 202 System error (should never occur).
 203 .RE
 204 
 205 .SH ATTRIBUTES
 206 See \fBattributes\fR(5) for descriptions of the following attributes:
 207 .sp
 208 
 209 .sp
 210 .TS
 211 box;
 212 c | c
 213 l | l .
 214 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 215 _
 216 Interface Stability     Committed
 217 .TE
 218 
 219 .SH SEE ALSO
 220 \fBdhcpagent\fR(1M), \fBifconfig\fR(1M), \fBdhcp_inittab\fR(4),
 221 \fBattributes\fR(5)
 222 .sp
 223 .LP
 224 Alexander, S., and R. Droms, \fIRFC 2132, DHCP Options and BOOTP Vendor
 225 Extensions\fR, Silicon Graphics, Inc., Bucknell University, March 1997.
 226 .sp
 227 .LP
 228 Droms, R. , \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6
 229 (DHCPv6)\fR, Cisco Systems, July 2003.
 230 .sp
 231 .LP
 232 Mockapetris, P.V. , \fIRFC 1035, Domain names - implementation and
 233 specification\fR, ISI, November 1987.