zipl/man/zipl.8

   1 .TH ZIPL 8 "Nov 2009" "s390-tools"
   2 .SH NAME
   3 zipl \- boot loader for IBM S/390 and zSeries architectures
   4
   5 .SH SYNOPSIS
   6 .B zipl
   7 [OPTION] [SECTION]
   8
   9 .SH DESCRIPTION
  10 .B zipl
  11 is a boot loader tool for IBM S/390 and zSeries machines. It can be used to
  12 prepare devices for initial program load (IPL). The following functions are
  13 supported:
  14 .IP "     -"
  15 booting a Linux kernel with optional ramdisk and kernel command line
  16 .IP "     -"
  17 taking a snapshot of the current system status (system dump)
  18 .IP "     -"
  19 loading a data file to initialize named saved segments (NSS)
  20 .PP
  21 Each of these operations is characterized by a boot configuration, i.e. a
  22 set of required parameters.
  23 .B zipl
  24 supports two ways of specifying a boot configuration:
  25 .IP "     -"
  26 .B command line:
  27 all parameters are provided through the command line switches described below.
  28 Using this mode, only a single boot configuration can be specified.
  29 .IP "     -"
  30 .B configuration file:
  31 parameters are provided by sections defined in a configuration file (see
  32 .BR zipl.conf (5)).
  33 Using a configuration file, you can either specify a single boot configuration
  34 or a menu, i.e. a list of configurations defined by a special section.
  35 .PP
  36
  37 To use a single boot configuration section, provide its name as parameter to
  38 .BR zipl .
  39 If
  40 .B zipl
  41 is called without parameters, it searches the configuration file for a
  42 section marked as default.
  43
  44 .B Boot menu
  45
  46 The
  47 .B zipl
  48 tool implements a boot menu which includes the following features:
  49 .IP "     -"
  50 display a list of available configurations
  51 .IP "     -"
  52 allow to choose a configuration
  53 .IP "     -"
  54 allow to specify additional kernel command line parameters
  55 .PP
  56
  57 See the
  58 .BR zipl.conf (5)
  59 man page for details on how to use the boot menu.
  60
  61 .B Logical devices
  62
  63 zipl can be used to prepare logical devices (e.g. a linear device mapper target)
  64 for booting when the following requirements are met by the logical device setup:
  65 .IP "     -"
  66 all boot relevant files (i.e. kernel, ramdisk and parameter files) must be
  67 located on a logical device which is mapped to a single physical disk of a type
  68 supported by zipl (i.e. DASD or SCSI disk)
  69 .IP "     -"
  70 adjacent data blocks on the logical device must correspond to adjacent blocks on
  71 the physical device
  72 .IP "     -"
  73 access to the first blocks (starting at block 0) of the physical device must be
  74 given
  75 .PP
  76 Examples for logical device setups that are supported are linear and mirror
  77 mapping.
  78
  79 When working with logical devices, zipl requires that the user provides more
  80 information about the target device:
  81 .IP "     -"
  82 device characteristics of the underlying physical device: disk type and format
  83 (e.g. ECKD CDL or FCP SCSI), disk geometry in case of ECKD DASDs and block size
  84 .IP "     -"
  85 target device offset, i.e. the number of blocks between the physical device
  86 start and the start of the logical device containing the filesystem with all
  87 boot relevant files
  88 .IP "     -"
  89 a device node which provides access to the first blocks of the device
  90 .PP
  91 If the user does not provide this information explicitly by parameters
  92 zipl automatically runs a driver specific helper script to obtain these data,
  93 e.g. zipl_helper.device-mapper.
  94
  95 Note that zipl uses /proc/devices to determine the driver name for a given
  96 device. If the driver name cannot be determined the preparation of a logical
  97 device for boot might fail.
  98 This can be the case in a chroot environment when /proc is not mounted
  99 explicitly.
 100
 101 .SH OPTIONS
 102 .TP
 103 .BR "\-h" " or " "\-\-help"
 104 Print usage information, then exit.
 105
 106 .TP
 107 .BR "\-v" " or " "\-\-version"
 108 Print version information, then exit.
 109
 110 .TP
 111 .BR "\-c <CONFIG FILE>" " or " "\-\-config=<CONFIG FILE>"
 112 Use the specified <CONFIG FILE>. If none is supplied, the environment
 113 variable ZIPLCONF is evaluated if set, otherwise /etc/zipl.conf is used.
 114
 115 .TP
 116 .BR "\-t <TARGET DIRECTORY>" " or " "\-\-target=<TARGET DIRECTORY>"
 117 Use the specified <TARGET DIRECTORY>.
 118 .B zipl
 119 uses this directory to store the bootmap, i.e. a file containing
 120 boot data. The actual boot loader is installed onto the device containing
 121 the target directory. Supported devices are DASD and SCSI disks.
 122
 123 It is not possible to specify both this parameter and the name of a menu
 124 or configuration section on the command line at the same time.
 125
 126 .TP
 127 .BR "\-\-targetbase=<BASE DEVICE>"
 128 Install the actual boot loader on the device node specified by BASE DEVICE.
 129
 130 This option is required when working with logical devices (see section
 131 "Logical devices" above).
 132
 133 .TP
 134 .BR "\-\-targettype=<TARGET TYPE>"
 135 Assume that the physical device is of the specified type. Valid values are:
 136 .IP "         -" 12
 137 CDL: DASD disk with ECKD/compatible disk layout
 138 .IP "         -" 12
 139 LDL: DASD disk with ECDK/linux disk layout
 140 .IP "         -" 12
 141 FBA: FBA disk DASD
 142 .IP "         -" 12
 143 SCSI: SCSI disk
 144 .PP
 145 .IP " " 8
 146 This option is required when working with logical devices (see section
 147 "Logical devices" above).
 148
 149 .TP
 150 .BR "\-\-targetgeometry=<CYLINDERS,HEADS,SECTORS>"
 151 Assume that the physical device has the specified number of cylinders, heads and
 152 sectors.
 153
 154 This option is required when working with logical devices which are located on
 155 DASD ECKD disks (see section "Logical devices" above).
 156
 157 .TP
 158 .BR "\-\-targetblocksize=<SIZE>"
 159 Assume that blocks on the physical device are SIZE bytes long.
 160
 161 This option is required when working with logical devices (see section
 162 "Logical devices" above).
 163
 164 .TP
 165 .BR "\-\-targetoffset=<OFFSET>"
 166 Assume that the logical device containing the directory specified by the
 167 --target option is located on the physical device starting at the block
 168 specified by OFFSET.
 169
 170 This option is required when working with logical devices (see section
 171 "Logical devices" above).
 172
 173 .TP
 174 .BR "\-T <TAPE DEVICE>" " or " "\-\-tape=<TAPE DEVICE>"
 175 Install bootloader on the specified <TAPE DEVICE>. Use this option instead
 176 of the 'target' option to prepare a tape device for IPL.
 177
 178 It is not possible to specify both this parameter and the name of a menu
 179 or configuration section on the command line at the same time.
 180
 181 .TP
 182 .BR "\-i <IMAGE[,ADDRESS]>" " or " "\-\-image=<IMAGE[,ADDRESS]>"
 183 Use the Linux kernel image file <IMAGE>. An optional hexadecimal
 184 ADDRESS may be provided to specify a non-standard load address for the
 185 image file.
 186
 187 It is not possible to specify both this parameter and the name of a menu
 188 or configuration section on the command line at the same time.
 189
 190 .TP
 191 .BR "\-r <RAMDISK[,ADDRESS]>" " or " "\-\-ramdisk=<RAMDISK[,ADDRESS]>"
 192 Use the ramdisk image <RAMDISK>. An optional hexadecimal
 193 ADDRESS may be provided to specify a non-standard load address for the
 194 ramdisk file.
 195
 196 It is not possible to specify both this parameter and the name of a menu
 197 or configuration section on the command line at the same time.
 198
 199 .TP
 200 .BR "\-p <PARMFILE[,ADDRESS]>" " or " "\-\-parmfile=<PARMFILE[,ADDRESS]>"
 201 Use the kernel command line stored in file <PARMFILE>. An optional hexadecimal
 202 ADDRESS may be provided to specify a non-standard load address for the
 203 parameter file.
 204
 205 It is not possible to specify both this parameter and the name of a menu
 206 or configuration section on the command line at the same time.
 207
 208 .TP
 209 .BR "\-P <PARMLINE>" " or " "\-\-parameters=<PARMLINE>"
 210 When installing a kernel, use the kernel command line <PARMLINE>.
 211 When --parmfile is specified as well, the contents of the parmfile
 212 and <PARMLINE> are appended to form the resulting command line.
 213
 214 It is not possible to specify both this parameter and the name of a menu
 215 section on the command line at the same time.
 216
 217 .TP
 218 .BR "\-s <SEGMENT,ADDRESS>" " or " "\-\-segment=<SEGMENT,ADDRESS>"
 219 Use the segment image <SEGMENT>. The mandatory hexadecimal ADDRESS specifies
 220 the load address for the segment file.
 221
 222 It is not possible to specify both this parameter and the name of a menu
 223 or configuration section on the command line at the same time.
 224
 225 .TP
 226 .BR "\-d <DEVNODE[,SIZE]>" " or " "--dumpto=<DEVNODE[,SIZE]>"
 227 Install a system dump record on the device identified by DEVNODE.
 228 Supported devices are DASD ECKD or FBA disk partitions
 229 and IBM 3480/3490/3590 tape devices.
 230
 231 An optional decimal SIZE parameter may be specified to determine the
 232 maximum dump size in bytes. SIZE can be suffixed by either of the letters
 233 K, M or G to signify that the decimal number be interpreted as kilobytes,
 234 megabytes or gigabytes respectively. SIZE will be rounded up to the next
 235 megabyte boundary. Note that when you specify a SIZE lower than the actual
 236 memory size used by linux (see kernel parameter mem=), the resulting dump
 237 will be incomplete.
 238
 239 Note that on partitions formatted with the ECKD/linux disk layout, the dump
 240 record will be overwritten by system dump data so that it can be used for
 241 IPL only once before the system dump record has to be installed again.
 242 Partitions formatted with the ECKD/compatible disk layout allow for an
 243 arbitrary number of subsequent dumps.
 244
 245 It is not possible to specify both this parameter and the name of a menu
 246 or configuration section on the command line at the same time.
 247
 248 .TP
 249 .BR "\-D <DEVNODE[,SIZE]>" " or " "--dumptofs=<DEVNODE[,SIZE]>"
 250 Install a dump record on the target device which writes system dumps to the
 251 file system on the disk partition identified by DEVNODE if supported by the
 252 hardware.
 253
 254 An optional decimal SIZE parameter may be specified to determine the
 255 maximum dump size in bytes. SIZE can be suffixed by either of the letters
 256 K, M or G to signify that the decimal number be interpreted as kilobytes,
 257 megabytes or gigabytes respectively. SIZE will be rounded up to the next
 258 megabyte boundary. Note that when you specify a SIZE lower than the actual
 259 memory size used by linux (see kernel parameter mem=), the resulting dump
 260 will be incomplete.
 261
 262 It is not possible to specify both this parameter and the name of a menu
 263 or configuration section on the command line at the same time.
 264
 265 .TP
 266 .BR "\-M <DUMPLIST[,SIZE]>" " or " "--mvdump=<DUMPLIST[,SIZE]>"
 267 Install a multi-volume dump record on each device associated with one of the
 268 partitions listed in file DUMPLIST.
 269 Supported are DASD ECKD partitions formatted with the compatible
 270 disk layout. A dump signature is written to each partition contained in
 271 DUMPLIST.
 272
 273 An optional decimal SIZE parameter may be specified to determine the
 274 maximum dump size in bytes. SIZE can be suffixed by either of the letters
 275 K, M or G to signify that the decimal number be interpreted as kilobytes,
 276 megabytes or gigabytes respectively. SIZE will be rounded up to the next
 277 megabyte boundary. Note that when you specify a SIZE lower than the actual
 278 memory size used by linux (see kernel parameter mem=), the resulting dump
 279 will be incomplete.
 280
 281 This option is useful if the actual memory size used by linux is
 282 larger than any single ECKD DASD partition could hold.
 283
 284 It is not possible to specify both this parameter and the name of a menu
 285 or configuration section on the command line at the same time.
 286
 287 .TP
 288 .BR "\-m <MENU>" " or " "--menu=<MENU>"
 289 Install the multi-boot configuration defined in menu section <MENU> of the
 290 configuration file.
 291
 292 This option cannot be used together with either
 293 .BR \-\-target ,
 294 .BR \-\-image ,
 295 .BR \-\-ramdisk ,
 296 .BR \-\-parmfile ,
 297 .BR \-\-parameters ,
 298 .BR \-\-segment ,
 299 .BR \-\-dumpto ,
 300 .BR \-\-dumptofs " or"
 301 .BR \-\-mvdump .
 302
 303 .TP
 304 .BR "\-n" " or " "\-\-noninteractive"
 305 Answer all confirmation questions with 'yes'. This option may be useful when
 306 .B zipl
 307 is called from within a shell script or in other situations where no user
 308 interaction is possible.
 309
 310 .TP
 311 .BR "\-V" " or " "\-\-verbose"
 312 Provide more verbose output.
 313
 314 .TP
 315 .BR "\-a" " or " "\-\-add-files"
 316 Copy all specified files to the bootmap file instead of just referencing them.
 317 This option allows specifying files in a boot configuration which are not
 318 located on the target device.
 319
 320 .TP
 321 .B "\-\-dry\-run"
 322 Print the results of performing the specified action without actually changing
 323 the IPL records. This option can be used to test a configuration since all
 324 error-checking is still done.
 325
 326 Note that when working with tapes, the current device position will be changed
 327 even when specifying this option.
 328
 329 .TP
 330 .BR "\-f" " or " "\-\-force"
 331 Omit validity checking while producing a multi-volume dump.
 332 Multi-volume dump partitions will be overwritten with dump data no matter
 333 whether they contain a dump signature or not.
 334
 335 This option can only be used together with
 336 .BR \-\-mvdump .
 337
 338 .SH EXAMPLE
 339 1. Scenario: prepare disk for booting a Linux kernel image using the
 340 following parameters:
 341 .br
 342   - the directory /boot is located on the boot device
 343 .br
 344   - /boot/image contains the Linux kernel image
 345 .br
 346   - /boot/ramdisk.img contains a ramdisk image
 347 .br
 348   - /boot/parmfile contains the kernel parameter line
 349 .br
 350
 351 .RB "The respective " "zipl " "call reads:"
 352 .br
 353
 354   zipl -t /boot -i /boot/image -r /boot/ramdisk.img
 355 .br
 356        -p /boot/parmfile
 357 .br
 358
 359 2. Scenario: prepare DASD partition /dev/dasda1 for system dump:
 360 .br
 361
 362   zipl -d /dev/dasda1
 363 .br
 364
 365 .SH SEE ALSO
 366 .BR zipl.conf (5)