Added some line breaks in BOOTPROTO section.
[opensuse:chkpnts-sysconfig.git] / doc / README.netconfig
1 #  README.netconfig
2 #  
3 #  netconfig is part of the sysconfig package
4 #  authors: Michael Calmer <mc@novell.com>,
5 #           Milisav Radmanic <radmanic@novell.com>,
6 #           Marius Tomaschewski <mt@novell.com>
7
8
9
10  * Network configuration tool (netconfig) *
11 =======================================================
12
13     NOTE: This README file may not contain all or obsolete details!
14     Please read the netconfig(8) manual page (man 8 netconfig) first.
15
16 The netconfig utility was written to handle netwok settings data, like
17 DNS, NIS, NTP from multiple sources as DHCP or PPP in the best way
18 possible.
19 This new script replaces the current "/sbin/modify_resolvconf" script!
20
21 The script itself is modular, so it is possible to extend or change its
22 functionality. Each module is responsible for a specific task.
23 The order in which the modules are called is defined in the sysconfig
24 variable NETCONFIG_MODULES_ORDER.
25
26 Static configuration values are written to sysconfig/network/config by
27 the yast-modules. Dhcp, ppp as well as the NetworkManager provide the
28 dynamic values directly to netconfig in a specified format.
29
30 Netconfig manages (stores or removes) the dynamic values and the netconfig 
31 modules merge all these informations depending on a predefined policy
32 and apply the required changes, for instance write a configuration file, 
33 restart a service and similar.
34
35 The prime objective here is: No process should alter the destination files 
36 directly, but pass its information through netconfig.
37
38 Every module has a policy-variable in sysconfig/network/config which tells
39 the module how to merge single values. Which interfaces should get recognized 
40 and which not or in which order and where it should use the static values.
41
42
43 Naming conventions:
44 -------------------
45
46 "static values":  values the user entered directly, e.g by a YaST module
47 "dynamic values": values delivered by dhcp or ppp (leases file) or the
48                   NetworkManager
49
50
51 The policy-variables:
52 --------------------
53
54 The policy-variables, lists the interfaces which should get addressed
55 if a configuration for this interface is available. You can use "*"
56 and/or "?" to match multiple interfaces. E.g. "eth* ppp?" will target
57 first all ethX interfaces and than ppp0-ppp9 interfaces.
58 Additionally it has two predefined static values which indicate what
59 should happen with the static configuration values:
60
61 - STATIC            is the placeholder for the static values set by
62                     yast-modules processed at the specific place in
63                     the order. (You can also use "auto" as a short
64                     for "STATIC *")
65
66 - STATIC_FALLBACK   defines, that dynamic values have priority, but
67                     if no dynamic values are available the STATIC
68                     ones are used
69
70 If the policy variable is empty, the configuration file will not be
71 changed by netconfig. This is useful if the user wants to keep the
72 sole control of the configuration file.
73
74 By default, the policy is set to the special value auto. This special
75 policy value is resolved by netconfig depending on the NETWORKMANAGER
76 ("yes"/"no") variable:
77 - NETWORKMANAGER = no
78         The auto policy value is resolved to a policy
79                 "STATIC *".
80
81 - NETWORKMANAGER = yes
82         The auto policy value is resolved to a policy
83                 "STATIC_FALLBACK NetworkManager"
84         causing to use the NetworkManager build-in merge policy
85         with a fallback to the static settings defined in
86         netconfig variables when the NetworkManager does not
87         provide any dynamic settings.
88
89         Note: The NetworkManager is not using any of the statically
90               defined netconfig settings (any more). This is required
91               to ensure a proper functionality of the NetworkManager.
92               Please use the (k)nm connection editor to define your
93               network settings for the NetworkManager!
94
95
96 The netconfig tool:
97 -------------------
98
99 The netconfig tool has three main commands:
100
101 * "modify" requires an interface dataset passed via STDIN (or file
102            specified via -i option). If a configuration already exists,
103            it will be replaced by the new one, otherwise it creates a
104            new configuration. After this, it updates the managed files
105            by calling the modules.
106
107 * "update" runs all the modules again. This is useful if the policy or
108            the static configuration changed. (this should be called most
109            of the time by yast-modules)
110
111 * "remove" removes an interface configuration defined by <service> and
112            <interface> and runs the modules again to bring the
113            configuration files up-to-date.
114
115 The data set which needs to be provided to "netconfig modify" is specified
116 as a simple key-value list compatible to the dhcpcd-leases format.
117 The keyword "INTERFACE" is mandatory. Here are examples of the currently
118 used key-value pairs:
119
120 INTERFACE='eth0'
121
122 The dns-resolver and dns-bind module recognizes the following keywords:
123 DNSDOMAIN='suse.de nue.novell.com'
124 DNSSERVERS='10.10.0.1 10.10.2.88'
125
126 The nis module recognizes the following keywords:
127 NISDOMAIN='novell.com'
128 NISSERVERS='149.44.160.146 149.44.160.50'
129
130 The ntp-runtime module recognizes the following keyword:
131 NTPSERVERS='149.44.160.50 149.44.160.54 149.44.160.1'
132
133 Additional netconfig options are:
134
135 options:                      mandatory for:
136   -s|--service <service>      modify, remove (e.g. dhcpcd, dhclient, etc.)
137   -i|--interface <interface>  remove         (e.g. eth0, ppp1, ...)
138   -l|--lease-file <file name>                lease / input file name
139   -F|--input-format <format>                 lease / input format (dhcpcd)
140   -f|--force_replace                         force overwriting of config files,
141                                              even when somebody changed them
142                                              manually
143   -v|--verbose                               print debug output
144
145
146
147 The Modules:
148 ------------
149
150 currently the following modules are provided:
151
152
153 dns-resolver:
154 -----------
155
156 DNS configuration consists of:
157     - domain search list
158     - nameserver ip list
159
160 The following variables are in /etc/sysconfig/network/config:
161
162     NETCONFIG_DNS_STATIC_SEARCHLIST=""
163     NETCONFIG_DNS_STATIC_SERVERS=""
164
165 The policy variable is named:
166
167     NETCONFIG_DNS_POLICY=""
168
169 The search list and nameservers are applied to /etc/resolv.conf.
170
171 Alternatively, the nameservers only may be applied as forwarders to the
172 configuration of a local nameserver. To identify such a configuration we
173 defined the variable:
174
175    NETCONFIG_DNS_FORWARDER=""
176
177 It can have the values:
178
179 * "resolv" or empty: no local DNS server, write to /etc/resolv.conf
180 * "bind"   : A bind nameserver is used as forwarder. Only the searchlist is
181              written to the /etc/resolv.conf; the nameserver are written to
182              the /etc/named.d/forwarders.conf.
183 * "dnsmasq": A dnsmasq nameserver is used as forwarder. Only the searchlist
184              is written to the /etc/resolv.conf; the nameserver are written
185              to the /var/run/dnsmasq-forwarders.conf.
186
187
188     Example:
189     --------
190
191     Static config in /etc/sysconfig/network/config:
192
193     NETCONFIG_DNS_POLICY="STATIC *"    # == "auto"
194     NETCONFIG_DNS_FORWARDER="resolv"
195
196     NETCONFIG_DNS_STATIC_SEARCHLIST="domain1 domain2"
197     NETCONFIG_DNS_STATIC_SERVERS="2001:cafe::1 10.0.0.1"
198
199         Resulting /etc/resolv.conf:
200             search domain1 domain2
201             nameserver 2001:cafe::1
202             nameserver 10.0.0.1
203
204     If a dynamic interface comes up (e.g. DHCP) with the values
205
206         DNSDOMAIN='domain2 domain3'
207         DNSSERVERS='10.10.0.1 10.10.2.88'
208
209     The result will be:
210
211         search domain1 domain2 domain3
212         nameserver 2001:cafe::1
213         nameserver 10.0.0.1
214         nameserver 10.10.0.1
215
216     [ 10.10.2.88 will not appear, because you can provide only 3 nameserver
217       in resolv.conf ]
218
219
220     If you change the NETCONFIG_DNS_POLICY variable to "eth* STATIC"
221     the resulting resolv.conf looks like this:
222
223         search domain2 domain3 domain1
224         nameserver 10.10.0.1
225         nameserver 10.10.2.88
226         nameserver 2001:cafe::1
227
228
229
230 nis:
231 ----
232
233 NIS configuration consists of:
234     - A list of domains with a list of server ip's for each domain
235
236 The following variables are defined in /etc/sysconfig/network/config:
237
238     NETCONFIG_NIS_STATIC_DOMAIN[_<number>]=""
239     NETCONFIG_NIS_STATIC_SERVERS[_<number>]=""
240
241 The values are applied to /etc/yp.conf . If the configuration changed
242 the nis module reloads ypbind. 
243
244
245 The policy variable is named:
246
247     NETCONFIG_NIS_POLICY=""
248
249 A special variable for this module is:
250
251     NETCONFIG_NIS_SETDOMAINNAME=""
252
253 It is a replacement for DHCLIENT_SET_DOMAINNAME in
254 /etc/sysconfig/network/dhcp.
255 Valid values are "no", "yes" or an interface name, e.g. eth0
256
257 - "no"         : netconfig do not set the domainname
258 - "yes"        : netconfig set the domainname with the first first
259                  interface which provide such a value.
260 - "<interface>": netconfig sets the domainname only when provided by
261                  the specified interface.
262
263
264     Example:
265     --------
266
267         Static config in /etc/sysconfig/network/config:
268
269         NETCONFIG_NIS_POLICY="STATIC *"
270
271             # first domain contains implicit _0 suffix:
272             NETCONFIG_NIS_STATIC_DOMAIN="defaultdomain"
273             NETCONFIG_NIS_STATIC_SERVERS="10.0.0.1 10.0.0.2"
274             # in case there is another domain:
275             NETCONFIG_NIS_STATIC_DOMAIN_1="anotherdomain"
276             NETCONFIG_NIS_STATIC_SERVERS_1="10.1.0.1 10.1.0.2"
277
278
279         Resulting /etc/yp.conf:
280             domain defaultdomain server 10.0.0.1
281             domain defaultdomain server 10.0.0.2
282             domain anotherdomain server 10.1.0.1
283             domain anotherdomain server 10.1.0.2
284
285     yp.conf knows other configuration values which are also possible
286     to configure:
287
288     NETCONFIG_NIS_STATIC_DOMAIN="defaultdomain"
289     NETCONFIG_NIS_STATIC_SERVERS="broadcast"
290
291     result in:
292
293         domain defaultdomain broadcast
294
295     NETCONFIG_NIS_STATIC_DOMAIN="defaultdomain"
296     NETCONFIG_NIS_STATIC_SERVERS="slp"
297
298     result in:
299
300         domain defaultdomain slp
301
302
303     NETCONFIG_NIS_STATIC_DOMAIN=""
304     NETCONFIG_NIS_STATIC_SERVERS="10.1.0.1"
305
306     result in:
307
308         ypserver 10.1.0.1
309
310     NETCONFIG_NIS_STATIC_DOMAIN="broadcast"
311     NETCONFIG_NIS_STATIC_SERVERS=""
312
313     result in:
314
315         broadcast
316
317     The behavior if a new interface comes up is like described for DNS
318     with the difference, that no values are dropped. yp.conf has no limit.
319
320
321
322 ntp-runtime:
323 ------------
324
325 NTP configuration consists of:
326     - A list of time server IP-addresses
327
328 The ntp handling is a little bit different. This module cannot manage the
329 complete ntp.conf. But ntp provides a feature which is called 
330 "runtime configuration" which is used by this module. 
331 This sets us in the convenient position that the yast2-ntp module
332 can still change /etc/ntp.conf and this module stores additional
333 timeservers at a different place. 
334
335 But to be compatible to other modules we defined also a variable in 
336 /etc/sysconfig/network/config including a policy. 
337
338     NETCONFIG_NTP_STATIC_SERVERS="
339
340 The values are applied to /var/run/ntp/servers-netconfig . If the
341 configuration changed meanwhile, ntp will be restarted (using try-restart). 
342
343 The policy variable is named:
344
345     NETCONFIG_NTP_POLICY=""
346
347
348     Example:
349     --------
350
351         Static config in /etc/sysconfig/network/config:
352             NETCONFIG_NTP_STATIC_SERVERS="10.0.0.1 10.1.0.1"
353
354         Resulting /var/run/ntp/servers-netconfig:
355                 RUNTIME_SERVERS="10.0.0.1 10.1.0.1"
356
357         The module script executes "rcntp try-restart" to apply the actual
358         ntp configuration at runtime.
359
360         FIXME: The init script should be extended to append the list of
361         timeservers from /var/run/ntp/servers to the list of the servers
362         maybe defined by the user in /etc/ntp.conf directly when it is
363         executing the initial ntptimeset action.
364         Further, when given (e.g. by ppp) the init script should also
365         use the "iburst" option for the runtime servers.
366