share/man/man5/ifconfig.if.5

   1 .\"     $NetBSD: ifconfig.if.5,v 1.18 2014/12/29 14:22:25 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1996 Matthew R. Green
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd December 18, 2014
  28 .Dt IFCONFIG.IF 5
  29 .Os
  30 .Sh NAME
  31 .Nm ifconfig.if
  32 .Nd interface-specific configuration files or variables
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 files or variables contain information regarding the configuration
  37 of each network interface.
  38 .Nm
  39 is processed by
  40 .Pa /etc/rc.d/network
  41 at system boot time.
  42 .Pp
  43 For each interface
  44 .Pq Ar nnX
  45 that is to be configured, there should be either an
  46 .Sy ifconfig_nnX
  47 variable in
  48 .Xr rc.conf 5 ,
  49 or an
  50 .Pa /etc/ifconfig.nnX
  51 file
  52 (such as the
  53 .Sy ifconfig_fxp0
  54 variable or the
  55 .Pa /etc/ifconfig.fxp0
  56 file for the
  57 .Sy fxp0
  58 interface).
  59 Only characters allowed in
  60 .Xr sh 1
  61 variables names should be used for
  62 .Ar nnX
  63 .Po Xr ascii 7
  64 uppercase and lowercase letters, digits, and underscore
  65 .Pc .
  66 .Pp
  67 The variable or file will get evaluated only if the interface exists on
  68 the system.
  69 Multiple lines can be placed in a variable or file, and will be
  70 evaluated sequentially.
  71 In the case of a variable, semicolons may be used instead of
  72 newlines, as described in
  73 .Xr rc.conf 5 .
  74 .Ao backslash Ac Ns Ao newline Ac
  75 sequences in files are ignored, so long logical lines may be
  76 made up of several shorter physical lines.
  77 .Pp
  78 Normally, a line will be evaluated as command line arguments to
  79 .Xr ifconfig 8 .
  80 .Dq Li ifconfig Ar nnX
  81 will be prepended on evaluation.
  82 Arguments with embedded shell metacharacters should be quoted in
  83 .Xr sh 1
  84 style.
  85 .Pp
  86 If the line is equal to
  87 .Dq dhcp ,
  88 .Xr dhcpcd 8
  89 will be started for the interface.
  90 However, it is instead recommended that
  91 .Sy dhcpcd
  92 is set to true in
  93 .Xr rc.conf 5
  94 and any per interface configuration or restriction is done in
  95 .Xr dhcpcd.conf 5 .
  96 .Pp
  97 If a line is empty, or starts with
  98 .Sq # ,
  99 the line will be ignored as comment.
 100 .Pp
 101 If a line starts with
 102 .Sq \&! ,
 103 the rest of line will get evaluated as shell script fragment.
 104 Shell variables declared in
 105 .Pa /etc/rc.d/network
 106 are accessible but may not be modified.
 107 The most useful variable is
 108 .Li $int ,
 109 as it will be bound to the interface being configured with the file.
 110 .Pp
 111 For example, the following illustrates static interface configuration:
 112 .Bd -literal -offset indent
 113 # IPv4, with an alias
 114 inet 10.0.1.12 netmask 255.255.255.0 media 100baseTX
 115 inet 10.0.1.13 netmask 255.255.255.255 alias
 116 # let us have IPv6 address on this interface
 117 inet6 2001:db8::1 prefixlen 64 alias
 118 # have subnet router anycast address too
 119 inet6 2001:db8:: prefixlen 64 alias anycast
 120 .Ed
 121 .Pp
 122 The following example sets a network name for a wireless interface
 123 (using quotes to protect special characters in the name),
 124 and starts
 125 .Xr dhcpcd 8 :
 126 .Bd -literal -offset indent
 127 ssid 'my network'
 128 dhcp
 129 .Ed
 130 .Pp
 131 The following example is for dynamically-created pseudo interfaces like
 132 .Xr gif 4 .
 133 Earlier versions of
 134 .Pa /etc/rc.d/network
 135 required an explicit
 136 .Sq create
 137 command for such interfaces,
 138 but creation is now handled automatically.
 139 .Bd -literal -offset indent
 140 up
 141 # configure IPv6 default route toward the interface
 142 !route add -inet6 default ::1
 143 !route change -inet6 default -ifp $int
 144 .Ed
 145 .Sh FILES
 146 .Pa /etc/rc.d/network
 147 .Sh SEE ALSO
 148 .Xr rc.conf 5 ,
 149 .Xr ifconfig 8