ipconfig.8   [plain text]


.\"
.\"     @(#)ipconfig.8
.\"
.Dd July 14, 2004
.Dt IPCONFIG 8
.Os "Mac OS X"
.Sh NAME
.Nm ipconfig
.Nd view and control IP configuration state
.Sh SYNOPSIS
.Nm
.Cm waitall
.Nm
.Cm getifaddr
.Ar interface-name
.Nm
.Cm ifcount
.Nm
.Cm getoption
.Ar interface-name
.Ar (option-name | option-code )
.Nm
.Cm getpacket
.Ar interface-name
.Nm
.Cm set
.Ar interface-name 
.Cm NONE
.Nm
.Cm set
.Ar interface-name
.Cm ( DHCP | BOOTP )
.Nm
.Cm set
.Ar interface-name
.Cm ( MANUAL | INFORM )
.Ar ip-address
.Ar subnet-mask
.Nm
.Cm setverbose
.Ar level
.Sh DESCRIPTION
.Nm 
is a utility that communicates with the IPConfiguration agent
to retrieve and set IP configuration parameters.  It should only be used 
in a test and debug context.  Using it for any other purpose is strongly 
discouraged.
Public API's in the SystemConfiguration framework are currently 
the only supported way to access and control the state of IPConfiguration.
.Pp
The IPConfiguration agent is responsible for configuring and managing the
IP addresses on direct, connectionless interfaces such as IEEE 802.3 Ethernet
and IEEE 1394 FireWire.  The IPConfiguration agent is a program bundle 
that is loaded and executed by the
.Xr configd 8
process.
.Pp
The IPConfiguration agent implements the client side of the DHCP and BOOTP
protocols described in RFC951, RFC1542, RFC2131, and RFC2132.  It also
assigns and maintains static IP addresses.  It may also allocate and 
assign a link-local IP address if DHCP fails to acquire an IP address.
.Pp
In all cases, the IPConfiguration agent performs IP address conflict detection
before assigning an IP address to an interface.
.Sh "COMMANDS"
The
.Nm
utility provides several commands:
.Pp
.Bl -tag -compact
.It Cm waitall
Blocks until all network services have completed configuring, or have timed 
out in
the process of configuring.  This is only useful for initial system start-up
time synchronization for legacy network services that are incapable of dealing
with dynamic network configuration changes.
.Pp
.It Cm getifaddr Ar interface-name
Prints to standard output the IP address for the first network service 
associated with the given interface.  The output will be empty if no
service is currently configured or active on the interface.
.Pp
.It Cm ifcount
Prints the number of interfaces that IPConfiguration is capable of configuring.
The value that's printed will not change unless relevant
network interfaces are either added to or removed from the system.
.Pp
.It Cm getoption Ar interface-name Ar ( option-name | option-code )
Prints the BOOTP/DHCP option with the given name or option code integer value.
See
.Xr bootpd 8
for option code names.
If an option has multiple values e.g. \fBdomain_name_server\fR, only the first
value is printed.
.Pp
.It Cm getpacket Ar interface-name
Prints to standard output the DHCP/BOOTP packet that the client accepted from
the DHCP/BOOTP server.  This command is useful to check what the server
provided, and whether the values are sensible.  This command outputs nothing
if DHCP/BOOTP is not active on the interface, or the attempt to acquire an 
IP address was unsuccessful.
.Pp
.It Cm set Ar interface-name Cm NONE
.It Cm set Ar interface-name Cm ( DHCP | BOOTP )
.It Cm set Ar interface-name Cm ( MANUAL | INFORM ) Ar ip-address Ar subnet-mask
Sets the interface to have a new temporary network service of the
given type.  All existing services on the interface are first de-configured
before the new service is instantiated.  If NONE is supplied, no new service
is instantiated.
.Pp
DHCP and BOOTP require no additional arguments. The IP address, subnet mask,
router, and DNS information are retrieved automatically.
.Pp
Both 
MANUAL and INFORM require the specification of an IP address
.Ar ip-address
and a subnet mask
.Ar subnet-mask .
.Pp
The INFORM service configures the IP address statically like MANUAL, but then
broadcasts DHCP INFORM packets to retrieve DHCP option
information. If the DHCP server responds and supplies a subnet mask, that
subnet mask is used instead of the specified
.Ar subnet-mask .
.Pp
The \fBset\fR command requires root privileges.
.Pp
\fBNote:\fR The \fBset\fR command is very useful for debugging, but it can't
be used to configure a persistent service.  The temporary services that are
created only remain until the next network configuration change occurs. See
.Xr scselect 8 .
.Pp
.It Cm setverbose Ar level
Sets verbose mode logging in the IPConfiguration agent. Specify a
.Ar level
value of
.Cm 0
to disable verbose logging, the default.  Specify a value of
.Cm 1
to enable verbose logging.
.Pp
When enabled, useful debugging information is logged using
.Xr syslog 3
with level LOG_NOTICE.
In addition, the packet trace file
\fB/var/log/com.apple.IPConfiguration.bootp\fR
is opened and BOOTP/DHCP packets that are sent and received are printed to the
file.
.Pp
The \fBsetverbose\fR command requires root privileges.
.El
.Sh "EXAMPLES"
.nf
# ipconfig getpacket en0
op = BOOTREPLY
htype = 1
dp_flags = 0
hlen = 6
hops = 0
xid = 1956115059
secs = 0
ciaddr = 0.0.0.0
yiaddr = 192.168.4.10
siaddr = 192.168.4.1
giaddr = 0.0.0.0
chaddr = 0:3:93:7a:d7:5c
sname = dhcp.mycompany.net
file = 
options:
Options count is 10
dhcp_message_type (uint8): ACK 0x5
server_identifier (ip): 192.168.4.1
lease_time (uint32): 0x164a
subnet_mask (ip): 255.255.255.0
router (ip_mult): {192.168.4.1}
domain_name_server (ip_mult): {192.168.4.1}
domain_name (string): mycompany.net
end (none): 
.fi
.Pp
.nf
# ipconfig getoption en0 router
192.168.4.1
.fi
.Sh "SEE ALSO"
.Lp
.Xr configd 8 ,
.Xr bootpd 8 ,
.Xr scselect 8
.Sh "HISTORY"
.Pp 
The
.Nm
command first appeared in Mac OS X Version 10.0 Public Beta.