ia64/xen-unstable

view tools/examples/xmexample2 @ 16739:33dcf04d7715

tools/docs: Fix example and default IP addresses.

In various places in documentation and code, IP addresses are provided
as examples, defaults, or dummy configuration. In general the
specific IP addresses used in Xen are not always appropriate. (For
example, 1.2.3.4 is used in a few places!)

The following addresses should be used:
* For examples and documentation, 192.0.2.0/24. (See RFC3330.)
* For defaults for private networks, a random network from RFC1918.
I have randomly selected 172.30.206.0/24 for this purpose and
documented this in at the only registry I know of,
www.ucam.org/cam-grin. This network should henceforth be used for
default configurations of local bridges, test networks, etc. in
Xen tools.

The following addresses should NOT be used:
* 10.0.*.*, 10.1.*.*, 192.168.0.*, 192.168.1.*, etc. Using these
addresses gives greatly increased likelihood of collision, as
ignorant network administrators and reckless middlebox vendors
often pick networks from the bottom of 10/8 and 192.168/16.
* 169.254.*.*. These are reserved for zeroconf (ad-hoc networking)
and should not be used for Xen private networks, bridges, etc.,
etc. Use of these addresses by Xen scripts causes trouble on hosts
(eg laptops) which find themselves in ad-hoc networking
environments. I think this is not hypothetical (!) since at least
one Linux distribution have specific code to detect this case and
cause Xen startup to fail iff the host already has an external
zeroconf address.
* 1.2.3.4. WTF !?

I have also used 127.0.255.255 in one place where apparently a dummy
address is needed (some Linux kernels won't accept a lack of an NFS
server address). If 127.0.255.255 is mistakenly used it is unlikely
to do any damage to real traffic even if it does escape into the
network at large.

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Jan 17 15:13:40 2008 +0000 (2008-01-17)
parents d2505c4ca32b
children 58e5e9ae0f8d
line source
1 # -*- mode: python; -*-
2 #============================================================================
3 # Example Python setup script for 'xm create'.
4 # This script sets the parameters used when a domain is created using 'xm create'.
5 #
6 # This is a relatively advanced script that uses a parameter, vmid, to control
7 # the settings. So this script can be used to start a set of domains by
8 # setting the vmid parameter on the 'xm create' command line. For example:
9 #
10 # xm create vmid=1
11 # xm create vmid=2
12 # xm create vmid=3
13 #
14 # The vmid is purely a script variable, and has no effect on the the domain
15 # id assigned to the new domain.
16 #============================================================================
18 # Define script variables here.
19 # xm_vars is defined automatically, use xm_vars.var() to define a variable.
21 # This function checks that 'vmid' has been given a valid value.
22 # It is called automatically by 'xm create'.
23 def vmid_check(var, val):
24 val = int(val)
25 if val <= 0:
26 raise ValueError
27 return val
29 # Define the 'vmid' variable so that 'xm create' knows about it.
30 xm_vars.var('vmid',
31 use="Virtual machine id. Integer greater than 0.",
32 check=vmid_check)
34 # Check the defined variables have valid values..
35 xm_vars.check()
37 #----------------------------------------------------------------------------
38 # Kernel image file.
39 kernel = "/boot/vmlinuz-2.6.10-xenU"
41 # Optional ramdisk.
42 #ramdisk = "/boot/initrd.gz"
44 # The domain build function. Default is 'linux'.
45 #builder='linux'
47 # Initial memory allocation (in megabytes) for the new domain.
48 #
49 # WARNING: Creating a domain with insufficient memory may cause out of
50 # memory errors. The domain needs enough memory to boot kernel
51 # and modules. Allocating less than 32MBs is not recommended.
52 memory = 64
54 # A name for the new domain. All domains have to have different names,
55 # so we use the vmid to create a name.
56 name = "VM%d" % vmid
58 # 128-bit UUID for the domain. The default behavior is to generate a new UUID
59 # on each call to 'xm create'.
60 #uuid = "06ed00fe-1162-4fc4-b5d8-11993ee4a8b9"
62 # List of which CPUS this domain is allowed to use, default Xen picks
63 #cpus = "" # leave to Xen to pick
64 #cpus = "0" # all vcpus run on CPU0
65 #cpus = "0-3,5,^1" # run on cpus 0,2,3,5
66 #cpus = "%s" % vmid # set based on vmid (mod number of CPUs)
68 # Number of Virtual CPUS to use, default is 1
69 #vcpus = 1
70 vcpus = 4 # make your domain a 4-way
72 #----------------------------------------------------------------------------
73 # Define network interfaces.
75 # By default, no network interfaces are configured. You may have one created
76 # with sensible defaults using an empty vif clause:
77 #
78 # vif = [ '' ]
79 #
80 # or optionally override backend, bridge, ip, mac, script, type, or vifname:
81 #
82 # vif = [ 'mac=00:16:3e:00:00:11, bridge=xenbr0' ]
83 #
84 # or more than one interface may be configured:
85 #
86 # vif = [ '', 'bridge=xenbr1' ]
88 vif = [ '' ]
90 #----------------------------------------------------------------------------
91 # Define the disk devices you want the domain to have access to, and
92 # what you want them accessible as.
93 # Each disk entry is of the form phy:UNAME,DEV,MODE
94 # where UNAME is the device, DEV is the device name the domain will see,
95 # and MODE is r for read-only, w for read-write.
97 # This makes the disk device depend on the vmid - assuming
98 # that devices sda7, sda8 etc. exist. The device is exported
99 # to all domains as sda1.
100 # All domains get sda6 read-only (to use for /usr, see below).
101 disk = [ 'phy:sda%d,sda1,w' % (7+vmid),
102 'phy:sda6,sda6,r' ]
104 #----------------------------------------------------------------------------
105 # Define frame buffer device.
106 #
107 # By default, no frame buffer device is configured.
108 #
109 # To create one using the SDL backend and sensible defaults:
110 #
111 # vfb = [ 'type=sdl' ]
112 #
113 # This uses environment variables XAUTHORITY and DISPLAY. You
114 # can override that:
115 #
116 # vfb = [ 'type=sdl,xauthority=/home/bozo/.Xauthority,display=:1' ]
117 #
118 # To create one using the VNC backend and sensible defaults:
119 #
120 # vfb = [ 'type=vnc' ]
121 #
122 # The backend listens on 127.0.0.1 port 5900+N by default, where N is
123 # the domain ID. You can override both address and N:
124 #
125 # vfb = [ 'type=vnc,vnclisten=127.0.0.1,vncdisplay=%d' % vmid ]
126 #
127 # Or you can bind the first unused port above 5900:
128 #
129 # vfb = [ 'type=vnc,vnclisten=0.0.0.0,vnunused=1' ]
130 #
131 # You can override the password:
132 #
133 # vfb = [ 'type=vnc,vncpasswd=MYPASSWD' ]
134 #
135 # Empty password disables authentication. Defaults to the vncpasswd
136 # configured in xend-config.sxp.
138 #----------------------------------------------------------------------------
139 # Define to which TPM instance the user domain should communicate.
140 # The vtpm entry is of the form 'instance=INSTANCE,backend=DOM'
141 # where INSTANCE indicates the instance number of the TPM the VM
142 # should be talking to and DOM provides the domain where the backend
143 # is located.
144 # Note that no two virtual machines should try to connect to the same
145 # TPM instance. The handling of all TPM instances does require
146 # some management effort in so far that VM configration files (and thus
147 # a VM) should be associated with a TPM instance throughout the lifetime
148 # of the VM / VM configuration file. The instance number must be
149 # greater or equal to 1.
150 #vtpm = ['instance=%d,backend=0' % (vmid) ]
152 #----------------------------------------------------------------------------
153 # Set the kernel command line for the new domain.
154 # You only need to define the IP parameters and hostname if the domain's
155 # IP config doesn't, e.g. in ifcfg-eth0 or via DHCP.
156 # You can use 'extra' to set the runlevel and custom environment
157 # variables used by custom rc scripts (e.g. VMID=, usr= ).
159 # Set if you want dhcp to allocate the IP address.
160 #dhcp="dhcp"
161 # Set netmask.
162 #netmask=
163 # Set default gateway.
164 #gateway=
165 # Set the hostname.
166 #hostname= "vm%d" % vmid
168 # Set root device.
169 root = "/dev/sda1 ro"
171 # Root device for nfs.
172 #root = "/dev/nfs"
173 # The nfs server.
174 #nfs_server = '192.0.2.1'
175 # Root directory on the nfs server.
176 #nfs_root = '/full/path/to/root/directory'
178 # Sets runlevel 4 and the device for /usr.
179 extra = "4 VMID=%d usr=/dev/sda6" % vmid
181 #----------------------------------------------------------------------------
182 # Configure the behaviour when a domain exits. There are three 'reasons'
183 # for a domain to stop: poweroff, reboot, and crash. For each of these you
184 # may specify:
185 #
186 # "destroy", meaning that the domain is cleaned up as normal;
187 # "restart", meaning that a new domain is started in place of the old
188 # one;
189 # "preserve", meaning that no clean-up is done until the domain is
190 # manually destroyed (using xm destroy, for example); or
191 # "rename-restart", meaning that the old domain is not cleaned up, but is
192 # renamed and a new domain started in its place.
193 #
194 # The default is
195 #
196 # on_poweroff = 'destroy'
197 # on_reboot = 'restart'
198 # on_crash = 'restart'
199 #
200 # For backwards compatibility we also support the deprecated option restart
201 #
202 # restart = 'onreboot' means on_poweroff = 'destroy'
203 # on_reboot = 'restart'
204 # on_crash = 'destroy'
205 #
206 # restart = 'always' means on_poweroff = 'restart'
207 # on_reboot = 'restart'
208 # on_crash = 'restart'
209 #
210 # restart = 'never' means on_poweroff = 'destroy'
211 # on_reboot = 'destroy'
212 # on_crash = 'destroy'
214 #on_poweroff = 'destroy'
215 #on_reboot = 'restart'
216 #on_crash = 'restart'
218 #============================================================================