man interfaces 覚書

``man interfaces`` の和訳。

# NAME
## /etc/network/interfaces
ifup と ifdown 用のネットワークインターフェイス設定。

# 基本書式

```
auto インターフェイス名

iface 論理インターフェイス名 アドレスファミリー メソッド
   メソッドのオプション
```

# DESCRIPTION
``/etc/network/interfaces`` は ``ifup(8)`` と ``ifdown(8)`` コマンド用の
ネットワークインターフェイスの設定情報を保有する。
システムがネットワークへどのように接続されるかを設定する。

``#`` から始まる行は無視される。

*Note:*
行末のコメントはサポートされていない。
コメントは必ずコメント行として独立させなければならない。

``\`` を行末に記述することで一文を複数行に分けて記述することができる。

ファイルは 0 や iface , mapping , auto , allow- , source 節から成り立つ。
下記に例を示す。

```
# ifup -a 実行時に eth0 インターフェイスを起動する。
auto eth0
# サブシステムによって eth1 を自動的に起動する。
allow-hotplug eth1

# interfaces.d/machine-dependent に記述された設定を読込む。
source interfaces.d/machine-dependent

# interfaces.d ディレクトリ配下の設定ファイルを読込む。
source-directory interfaces.d

# 物理インターフェイス eth0 の論理インターフェイス名設定
mapping eth0
   # /usr/local/sbin/map-scheme を実行する。
   script /usr/local/sbin/map-scheme
   # 論理インターフェイス名の関連付け
   map HOME eth0-home
   map WORK eth0-work

# 論理インターフェイス eth0-home の設定
iface eth0-home inet static
   address 192.168.1.1
   netmask 255.255.255.0
   up flush-mail

# 論理インターフェイス eth0-work の設定
iface eth0-work inet dhcp

# 論理インターフェイス eth1 の設定
iface eth1 inet dhcp
```

## auto
auto から始まる行は、 ``ifup -a`` が実行された時に
操作するインターフェイスを識別する為に使用する。
(``ifup -a`` はシステムの起動スクリプトによって使用される)
インターフェイス名は auto が記述されている行と同一の行に記述すること。
複数の auto 節を記述することができる。
ifup は ``/etc/network/interfaces`` に列記された インターフェイスを起動する。

## allow-
allow- から始まる行はサブシステムによって
自動的に起動されるべきインターフェイスを識別する為に使用される。
サブシステムによるインターフェイスの起動操作は
allow-hotplug の行にインターフェイス名が列記されている場合、
eth0 や eth1 のみを起動する ``ifup --allow=hotplug eth0 eth1`` のような
コマンドを使用して実行する場合がある。

*Note:*
allow-auto と auto は同義語。

## source
source から始まる行は他のファイルに記述された設定を読み込む為に使用される。
設定は複数のファイルに分割することができる。
source は指定されたパスのファイルを読み込む。
シェルワイルドカードを使用することができる。詳細は ``wordexp(3)`` を参照。

## source-directory
ファイルを個別に指定したり、シェルグラブを使用する代わりに、
source-directory キーワードを使用して、複数のファイルを一つにすることができる。

source-directory 使用時は下記の正規表現を使用して ファイル名を指定することができる。

```
^[a-zA-Z0-9_-]+$
```

他の語句は必ず大文字または小文字の ASCII 文字、 ASCII 数字、
ASCII アンダースコア、 ASCII ハイフンから構成する。
ディレクトリパス内ではシェルワイルドカードを使用する場合がある。

ファイルまたはディレクトリを読込む際、パスの先頭に ``/`` が無い場合、
値として指定したファイルを含むディレクトリへの相対パスとして認識される。
例えばファイルが ``/etc/network/interfaces`` にある場合、
ファイルを含むパスは ``/etc/network`` の配下と認識される。

既定では新規インストールされた Debian システムでは
インターフェイスファイルは ``/etc/network/interfaces.d`` ディレクトリから読み込まれる。

## mapping
mapping から始まる節は、起動する物理インターフェイスの
論理インターフェイス名の選定方法を決定する為に使用する。
mapping 節の最初の行は mapping に続くシェルグラブシンタックスのパターンから構成される。 
各 mapping 節は必ずスクリプト定義を含む必要がある。
名付けられたスクリプトは、引数として指定された物理インターフェイス名と、
標準入力上で map 節が提供する全ての map 行(先頭の map は除く)の内容で実行される。
スクリプトは終了前に必ず標準出力へ文字列を表示する必要がある。
スクリプトが表示しなければならない内容については
``/usr/share/doc/ifupdown/examples`` を参照。

マッピングする名前は、 mapping に続くパターンの検索から構成され、
最初の一致に対応するスクリプトを実行する。スクリプトはマッピング元の名前を出力する。

ifup は通常物理インターフェイス名を最初の非オプション引数として使用する。
ifup が LOGICAL をインターフェイスの初期論理名として選択する場合、
ifup は ``form =LOGICAL`` を末尾に伴わない限り
指定した物理インターフェイス名をインターフェイスの初期論理名として使用する。
ifup は、関連付けが終了するまで複数回、連続したマッピング仕様に従って名前を関連付ける。
処理の結果、名前が複数の定義済み論理インターフェイスと重複する場合、
ifup は物理インターフェイスを論理インターフェイスとして起動を試行する。
一方 ifup はエラーを発生させて終了する。

## iface
論理インターフェイスの定義は iface から始まり、
論理インターフェイス名が続く行で定義する。 
mapping 節を持たない単純な設定では、
論理インターフェイス名は物理インターフェイス名と同じにすること。
(既定では mapping スクリプトは echo コマンドに影響する)
インターフェイス名は、インターフェイスが使用するアドレスファミリーの名前の後に続く。
これは TCP / IP ネットワークの inet となり、
IPX ネットワーク(ipx)と、 IPv6 ネットワーク(inet6)もサポートする。
インターフェイスの設定に使用するメソッドの名前を以下に示す。

追加オプションは節の後に続く行の中で指定することができる。
オプションはファミリーとメソッドに依存する。
追加オプションは他の Debian パッケージを使用して作成することができる。
例えば wireless-tools パッケージは、 ``iwconfig(8)`` を使用して
設定するインターフェイスへ使用する wireless- 接頭辞オプションを作ることができる。
(詳細は ``wireless(7)`` を参照。)

オプションは通常、分かりやすくするためにインデントされるが、
インデントは必須ではない。(上記の例を参照)

# VLAN AND BRIDGE INTERFACES
VLAN インターフェイスの設定を容易にするために 
802.1q tagged virtual LAN interface として設定されたインターフェイスは 
名前の中に ``.`` (ドット) を保有する。 
例えば interface eth0.1 は物理リンクとして eth0 を持ち、 
VLAN ID 1 を持つ仮想インターフェイスとなる。

bridge-utils パッケージとの互換性の為、 
bridge-ports オプションが指定されている場合、 
VLAN インターフェイス設定は無効となる。

# IFACE OPTIONS
下記の ``command`` オプションは全てのファミリーとメソッドへ使用することができる。 
これらのオプションは一つの節の中に複数回指定することができる。 
一つの節の中に複数回指定する場合、コマンドは記述された順序で実行される。 
(末尾に ``|| true`` と記述することで、コマンドの失敗を防ぐことができる)

## pre-up command
インターフェイスを起動する前にコマンドを実行する。 
コマンドが失敗した場合、 ifup は中断される。 
インターフェイスの設定は適用されず、 
エラーメッセージを表示し、ステータス 0 で終了する。 
この動作は将来的に変更される可能性がある。

## up command, post-up command
インターフェイス起動後にコマンドを実行する。 
コマンドが失敗した場合、 ifup は中断される。 
(既に実際に設定済みであったとしても)
インターフェイスの設定は適用されず、 
エラーメッセージを表示し、ステータス 0 で終了する。 
この動作は将来的に変更される可能性がある。

## down command, pre-down command
インターフェイスを停止する前にコマンドを実行する。 
コマンドが失敗した場合、 ifdown は中断される。 
(まだ実際には設定が解除されていない場合でも) 
インターフェイスの設定解除は適用され、 
ステータス 0 で終了する。 
この動作は将来的に変更される可能性がある。

## post-down command
インターフェイス停止後にコマンドを実行する。 
コマンドが失敗した場合、 ifdown は中断される。 
インターフェイスの設定解除は適用され、ステータス 0 で終了する。 
この動作は将来的に変更される可能性がある。

オプションが処理された後に ``run-parts(8)`` を使用して 
(引数なしで)実行されるスクリプトは、 
それぞれのオプション毎にディレクトリ 
``/etc/network/if-<option>.d/`` を作成する。

*Note:*
post-up と pre-down はエイリアスであり、 
実行中のディレクトリに対応するファイルは存在しない。 
``if-up.d`` と ``if-down.d`` を代わりに使用すること。

これらのコマンドは全て下記の環境変数を参照する。

## IFACE
実行中の物理インターフェイスの名前。

## LOGICAL
実行中の論理インターフェイスの名前。

## ADDRFAM
インターフェイスのアドレスファミリー。

## METHOD
インターフェイスのメソッド(例, static)

## MODE
ifup 実行時に起動し、 ifdown 実行時に停止する。

## PHASE
MODE 毎に細かい粒度で 
pre-up, post-up, pre-down, post-down フェーズを区別する。

## VERBOSITY
``–verbose`` が使用されたかどうかを表す。 
``–verbose`` が使用されている場合は 1 を、 
使用されていない場合は 0 が設定される。

## PATH
コマンド検索パス。

```
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```

インターフェイスの定義節の中で指定されたオプションは全て
英数字ではない文字を切捨て、 ``-`` を ``_`` へ変換し、 
大文字 ``IF_`` を先頭に付与して環境変数としてエクスポートされる。

ifupdown が ``–all`` オプションを使用して呼び出されている時、 
インターフェイスへ何かを行う前に、 
全てのフックスクリプト(pre-up または down)を 
``--all`` を設定した IFACE で呼び出す場合、 
LOGICAL は現在の ``–allow`` パラメータの値(設定されていない場合は auto)を設定し、 
``ADDRFAM="meta"`` と ``METHOD="none"`` を設定する。 
全てのインターフェイスが起動または停止した後、 
適切なスクリプト(up または post-down)が実行される。

# INET ADDRESS FAMILY
inet address family で使用可能なメソッド。

## loopback Method
このメソッドは IPv4 loopback interface の定義に使用されることがある。

### Options
(オプションなし)

## static Method
このメソッドは Ethernet interface の 固定 IPv4 アドレスの定義に使用されることがある。

### Options
#### *address address*
Address (dotted quad/netmask) required

#### *netmask mask*
Netmask (dotted quad or CIDR)

#### *broadcast broadcast_address*
Broadcast address (dotted quad, ``+`` or ``-``). 
既定値: ``+``

#### *metric metric*
Routing metric for default gateway (integer)

#### *gateway address*
Default gateway (dotted quad)

#### *pointopoint address*
Address of other end point (dotted quad). 

*Note:* 
the spelling of ``pointto`` .

#### *hwaddress address*
Link local address.

#### *mtu size*
MTU size

#### *scope*
アドレスの検証範囲。

使用可能な値:

* global
* link
* host

## manual Method
このメソッドは、何も設定しないことを既定とする 
インターフェイスの定義に使用されることがある。 
何も設定しないことを既定とするインターフェイスは up / down コマンド
または ``/etc/network/if-*.d`` スクリプトを使用して 
手動で設定することができる。

### Options
#### *hwaddress address*
Link local address.

#### *mtu size*
MTU size

## dhcp Method
このメソッドは DHCP を介してアドレスを取得するツールで使用されることがある。

* dhclient
* pump
* udhcpc
* dhcpcd

(優先度順に並べたリスト)

*Note:*
複雑な DHCP 設定を持つ場合、クライアントによっては独自の設定ファイルを使用し、 
ifup を介して設定情報を取得しないことに注意。

### Options
#### *hostname hostname*
Hostname to be requested (pump, dhcpcd, udhcpc)

#### *metric metric*
Metric for added routes (dhclient)

#### *leasehours leasehours*
リース時間を時間単位で設定する。(pump)

#### *leasetime leasetime*
リース時間を秒単位で設定する。(dhcpcd)

#### *vendor vendor*
Vendor class identifier (dhcpcd)

#### *client client*
Client identifier (dhcpcd, udhcpc)

#### *hwaddress address*
Hardware address.

## bootp Method
このメソッドは bootp を介したアドレスの取得に使用されることがある。

### Options
#### *bootfile file*
file を bootfile として使用することをサーバへ通知する。

#### *server address*
サーバとの交信に使用する IP アドレス。

#### *hwaddr addr*
実際のハードウェアアドレスの代わりに addr をハードウェアアドレスとして使用する。

## tunnel Method
このメソッドは GRE トンネルまたは IPIP トンネルの作成に使用されることがある。 
iproute パッケージの ip バイナリが必要となる。 
GRE トンネルの場合、 ip_gre モジュールの読み込みが必要となり、 
IPIP トンネルの場合は ipip モジュールの読み込みが必要となる。

### Options
#### *address address*
Local address (dotted quad) required

#### *mode type*
Tunnel type (either GRE or IPIP) required

#### *endpoint address*
Address of other tunnel endpoint required

#### *dstaddr address*
Remote address (remote address inside tunnel)

#### *local address*
Address of the local endpoint

#### *gateway address*
Default gateway

#### *ttl time*
TTL setting

#### *mtu size*
MTU size

## ppp Method
このメソッドは pon / poff を使用して PPP インターフェイスを設定する。 
詳細は command を参照。

### Options
#### *provider name*
name をプロバイダとして使用する(from ``/etc/ppp/peers``).

#### *unit number*
ppp unit number として使用する数値。

#### *options string*
string を pon へ追加オプションとして渡す。

## wvdial Method
このメソッドは wvdial を使用して PPP インターフェイスを設定する。 
詳細は command を参照。

### Options
#### *provider name*
name をプロバイダとして使用する。(from ``/etc/wvdial.conf``)

## ipv4ll Method
このメソッドは avahi-autoipd を使用して、 
インターフェイスの IPv4 Link-Layer address(169.254.0.0/16 family)を設定する。 
このメソッドは APIPA または IPAC として知られ、 
しばしば口語的に Zeroconf address として参照される。

### Options
(オプションなし)

# IPX ADDRESS FAMILY
ipx address family において使用可能なメソッド。

## static Method
このメソッドは IPX インターフェイスの設定に使用する。 
static メソッドは ipx_interface コマンドが必要とする。

### Options
#### *frame type*
使用する Ethernet フレームの種類。(例: 802.2)

#### *netnum id*
Network number

## dynamic Method
このメソッドは IPX インターフェイスを動的に設定する。

### Options
#### *frame type*
使用する Ethernet フレームの種類。(例: 802.2)

# INET6 ADDRESS FAMILY
inet6 address family において使用可能なメソッド。

## auto Method
このメソッドはインターフェイスへ自動的に IPv6 アドレスを割当てるように設定する。 
RDNSS オプションは auto メソッドを使用するだけでは適用されない。 
RDNSS オプションを適用する為には、 rdnssd デーモンを必ずインストールし、
適切な設定を行って実行する必要がある。 
stateless DHCPv6 サポートが有効な場合、 
DNS のようなネットワークの追加設定パラメータと 
NTP サーバは DHCP サーバから取得される。

*Note:*
リースは ifdown 実行時にリリースされない。(既知のバグ)

### Options
#### *privext int*
Privacy extensions (RFC4941) 

* 0=off
* 1=assign
* 2=prefer

#### *dhcp int*
stateless DHCPv6 を使用する。

* 0=off
* 1=on

## loopback Method
このメソッドは IPv6 loopback interface を定義する。

### Options
(オプションなし)

## static Method
インターフェイスへ固定 IPv6 アドレスの割当てを定義する。 
既定では stateless autoconfiguration はこのインターフェイスでは無効となる。

### Options
#### *address address*
Address (colon delimited/netmask) required

#### *netmask mask*
Netmask (number of bits, eg 64)

#### *gateway address*
Default gateway (colon delimited)

#### *media type*
メディアの種類(ドライバに依存する)

#### *hwaddress address*
Hardware address

#### *mtu size*
MTU size

#### *accept_ra int*
Accept router advertisements 

* 0=off
* 1=on

#### *autoconf int*
stateless autoconfiguration を実行する。

* 0=off
* 1=on

既定値: ``0``

#### *privext int*
Privacy extensions (RFC3041) 

* 0=off
* 1=assign
* 2=prefer

#### *scope*
アドレスの検証範囲。

使用可能な値:

* global
* site
* link
* host

#### *preferred-lifetime int*
Time that address remains preferred

#### *dad-attempts*
DAD を解決するための試行回数。(0 = disable)
既定値: ``60``

#### *dad-interval*
DAD ポーリング間隔を秒単位で指定する。
既定値: ``0.1``

## manual Method
このメソッドは、インターフェイスへ何も設定を行わないことを定義する。 
manual が定義されたインターフェイスは up コマンド、 down コマンド、 
``/etc/network/if-*.d`` スクリプト等を用いて手動設定することができる。

### Options
#### *hwaddress address*
Hardware address

#### *mtu size*
MTU size

## dhcp Method
このメソッドは dhclient の stateful DHCPv6 を介した
ネットワークインターフェイス設定の取得に使用される。 
stateful DHCPv6 では DHCP サーバは、クライアントへアドレスを割当てる責任がある。

### Options
#### *hwaddress address*
Hardware address
    
#### *accept_ra int*
Accept router advertisements 

* 0=off
* 1=on

既定値: ``0``
    
#### *autoconf int*
stateless autoconfiguration を実行する。

* 0=off
* 1=on

## v4tunnel Method
このメソッドは IPv6-over-IPv4 tunnel の設定に使用される。 
v4tunnel メソッドは iproute パッケージの ip コマンドを必要とする。

### Options
#### *address address*
Address (``:`` 区切り) required
    
#### *netmask mask*
Netmask (ビット数。例: 64)
    
#### *endpoint address*
Address of other tunnel endpoint (IPv4 dotted quad) required
    
#### *local address*
Address of the local endpoint (IPv4 dotted quad)
    
#### *gateway address*
Default gateway (``:`` 区切り)
    
#### *ttl time*
TTL setting
    
#### *mtu size*
MTU size

## 6to4 Method
このメソッドは 6to4 tunnel の設定に使用される。 
6to4 メソッドは iproute パッケージの ip コマンドを必要とする。

### Options
#### *local address*
Address of the local endpoint (IPv4 dotted quad) required
    
#### *ttl time*
TTL setting
    
#### *mtu size*
MTU size

# CAN ADDRESS FAMILY
can address family で使用可能なメソッド。

## static Method
このメソッドは Controller Area Network (CAN) interface の設定に使用される。 
static メソッドは iproute パッケージの ip コマンドを必要とする。

### Options
#### *bitrate bitrate*
bitrate (1..1000000) required
    
#### *samplepoint samplepoint*
sample point (0.000..0.999)
    
#### *loopback loopback*
loop back CAN Messages 

* on
* off
    
#### *listenonly listenonly*
listen only mode 

* on
* off
    
#### *triple triple*
triple sampling を有効にする。

* on
* off
    
#### *oneshot oneshot*
one shot mode 

* on
* off
    
#### *berr berr*
berr 報告を有効にする。

* on
* off

# KNOWN BUGS / LIMITATIONS
ifup と ifdown プログラムは物理インターフェイス名で動作する。 
物理インターフェイス名はカーネルによってハードウェアへ割当てられる。 
残念なことに、カーネルはシステムを起動する度に、 
同一のハードウェアへ異なる物理インターフェイス名を割当てることがある。 
例えば前回の起動時には eth0 と名前が付いていたのに、 
現在の起動時には eth1 と名前を付けることがある。 
この動作はインターフェイスへ適切な設定を行えなくなる問題を発生させる。 
問題を解決するには、インターフェイスハードウェアのプロパティに従って
論理インターフェイス名を選択する mapping スクリプトを使用する。 
mapping スクリプトの例を格納している examples ディレクトリ内の 
``get-mac-address.sh`` スクリプトと Debian bug #101728　を参照。

# SEE ALSO
* ``ifup(8)``
* ``ip(8)``
* ``ifconfig(8)``
* ``run-parts(8)``
* ``resolvconf(8)``
* Debian Reference manual の [Network Configuration chapter](http://www.debian.org/doc/manuals/debian-ref%E2%80%90erence/ch05.en.html)
* debian-reference-en package の Network Configuration chapter

インターフェイスの設定例は 
[/usr/share/doc/ifupdown/examples/network-interfaces.gz](http://qiita.com/JhonnyBravo/items/bdc503892e17b42a430b) を参照。