1COBBLER(1) cobbler COBBLER(1)
2
6 cobbler is a provisioning and update server. It supports deployments
7 via PXE (network booting), virtualization (Xen or QEMU/KVM), and
8 re-installs of existing Linux systems. The latter two features are
9 enabled by usage of 'koan' on the remote system. Update server fea‐
10 tures include yum mirroring and integration of those mirrors with kick‐
11 start. Cobbler has a command line interface, Web UI, and extensive
12 Python and XMLRPC APIs for integration with external scripts and appli‐
13 cations.
14
16 cobbler command [subcommand] [--arg1=value1] [--arg2=value2]
17
19 Cobbler manages provisioning using a tiered concept of Distributions,
20 Profiles, Systems, and Repositories.
21 Distributions contain information about what kernel and initrd are
23 used, plus metadata (required kernel parameters, etc).
24 Profiles associate a Distribution with a kickstart file and optionally
26 customize the metadata further.
27 Systems associate a MAC, IP, and/or hostname with a profile and option‐
29 ally customize the metadata further.
30 Repositories contain yum mirror information. Using cobbler to mirror
32 repositories is an optional feature, though provisioning and package
33 management share a lot in common.
34 The main advantage of cobbler is that it glues together a lot of dis‐
36 joint technologies and concepts and abstracts the user from the need to
37 understand them. It allows the systems administrator to concentrate
38 on what he needs to do, and not how it is done.
39 This manpage will focus on the cobbler command line tool for use in
41 configuring cobbler. There is also mention of the Cobbler WebUI which
42 is usable for day-to-day operation of Cobbler once installed/config‐
43 ured. Docs on the API and XMLRPC components are available online at
44 http://cobbler.et.redhat.com and the companion Wiki:
45 https://hosted.fedoraproject.org/projects/cobbler/.
46 Most users will be interested in the Web UI and should set it up,
48 though the command line is needed for initial configuration -- in par‐
49 ticular "cobbler check" and "cobbler import".
50
52 For help in building kickstarts, try using the "system-config-kick‐
53 start" tool, or install a new system and look at the /root/ana‐
54 conda-ks.cfg file left over from the installer. General kickstart
55 questions can also be asked at kickstart-list@redhat.com. Cobbler
56 ships some kickstart templates in /etc/cobbler that may also prove
57 helpful.
58 Also see the aforementioned webpages for additional documentation, user
60 contributed tips, and so on.
61
63 SETUP
64 After installing, run "cobbler check" to verify that cobbler's ecosys‐
66 tem is configured correctly. Cobbler check will direct you on how to
67 modify it's config files using a text editor.
68 Any problems detected should be corrected, with the potential exception
70 of DHCP related warnings where you will need to use your judgement as
71 to whether they apply to your environment. Run "cobbler sync" after
72 making any changes to the configuration files to ensure those changes
73 are applied to the environment.
74 It is especially important that the server name field be accurate in
76 /etc/cobbler/settings, without this field being correct, kickstart
77 trees will not be found, and automated installtions will fail.
78 For PXE, if DHCP is to be run from the cobbler server, the dhcp config‐
80 uration file should be changed as suggested by "cobbler check". If
81 DHCP is not run locally, the "next-server" field on the DHCP server
82 should at minimum point to the cobbler server's IP and the filename
83 should be set to "pxelinux.0". Alternatively, cobbler can also gener‐
84 ate your dhcp configuration file if you want to run dhcp locally --
85 this is covered in a later section. If you don't already have a DHCP
86 setup managed by some other tool, allowing cobbler to manage DHCP will
87 prove to be useful as it can manage DHCP reservations and other data.
88 If you already have a DHCP setup, moving an existing setup to be man‐
89 aged from within cobbler is relatively painless -- though usage of the
90 DHCP management feature is entirely optional. If you are not inter‐
91 ested in network booting via PXE and just want to use koan to install
92 virtual systems or replace existing ones, DHCP configuration can be
93 totally ignored. Koan also has a live CD (see koan's manpage) capabil‐
94 ity that can be used to simulate PXE environments.
95 ADDING A DISTRIBUTION
97 This first step towards configurating what you want to provision is to
99 add a distribution to cobbler's configuration.
100 If there is an rsync mirror, DVD, NFS, or filesystem tree available
102 that you would rather import instead, skip down to the documentation
103 about the "import" command. It's really a lot easier, and it only
104 requires waiting for the mirror content to be copied and/or scanned.
105 Imported mirrors also save time during install since they don't have to
106 hit external install sources.
107 If you want to be explicit with distribution definition, however,
109 here's how it works:
110 cobbler distro add --name=string --kernel=path --initrd=path
112 [--kopts=string] [--ksmeta=string] [--arch=x86⎪x86_64⎪ia64]
113 [--breed=redhat⎪debian⎪suse]
114 name
116 a string identifying the distribution, this should be something
117 like "rhel4".
118 kernel
120 An absolute filesystem path to a kernel image
121 initrd
123 An absolute filesystem path to a initrd image
124 kopts
126 Sets kernel command-line arguments that the distro, and pro‐
127 files/systems dependant on it, will use.
128 Example: --kopts="foo=bar baz=3 asdf"
130 arch
132 Sets the architecture for the PXE bootloader
133 The default setting ('standard') will use pxelinux. Set to 'ia64'
135 to use elilo.
136 'x86' and 'x86_64' effectively do the same thing as standard.
138 ksmeta
140 This is an advanced feature that sets kickstart variables to sub‐
141 stitute, thus enabling kickstart files to be treated as templates.
142 Templates are powered using Cheetah and are described further along
143 in this manpage as well as on the Cobbler Wiki.
144 Example: --ksmeta="foo=bar baz=3 asdf"
146 See the section on "Kickstart Templating" for further information.
148 breed
150 Controls how kernel arguments for automatic installation are to be
151 treated. Defaults to "redhat", which is a suitable value for
152 Fedora and Centos as well. It means anything redhat based.
153 There is limited experimental support for specifying "debian" or
155 "suse", which treats the kickstart file as a different format and
156 changes the kernel arguments appropriately. Support for other
157 types of distributions is possible in the future.
158 The file used for the answer file, regardless of the breed setting,
160 is the value used for --kickstart when creating the profile.
161 owners
163 Users with small sites and a limited number of admins can probably
164 ignore this option. All cobbler objects (distros, profiles, sys‐
165 tems, and repos) can take a --owners parameter to specify what cob‐
166 bler users can edit particular objects. This only applies to the
167 Cobbler WebUI and XMLRPC interface, not the "cobbler" command line
168 tool run from the shell. Furthermore, this is only respected by
169 the "authz_ownership" module which must be enabled in /etc/cob‐
170 bler/modules.conf. The value for --owners is a comma seperated
171 list of users and groups as specified in /etc/cobbler/users.conf.
172 For more information see the users.conf file as well as the Cobbler
173 Wiki. In the default Cobbler configuration, this value is com‐
174 pletely ignored, as is users.conf.
175 ADDING A PROFILE
177 A profile associates a distribution to additional specialized options,
179 such as a kickstart automation file. Profiles are the core unit of
180 provisioning and at least one profile must exist for every distribution
181 to be provisioned. A profile might represent, for instance, a web
182 server or desktop configuration. In this way, profiles define a role
183 to be performed.
184 cobbler profile add --name=string --distro=string [--kickstart=path]
186 [--kopts=string] [--ksmeta=string] [--virt-file-size=gigabytes]
187 [--virt-ram=megabytes] [--virt-type=string] [--virt-cpus=integer]
188 [--virt-path=string] [--virt-bridge=string] [--server-override]
189 Arguments are as listed for distributions, save for the removal of
191 "arch" and "breed", and with the additions listed below:
192 name
194 A descriptive name. This could be something like "rhel4webservers"
195 or "fc6desktops".
196 distro
198 The name of a previously defined cobbler distribution
199 kickstart
201 Local filesystem path to a kickstart file. http:// URLs (even
202 CGI's) are also accepted, but a local file path is recommended, so
203 that the kickstart templating engine can be taken advantage of.
204 If this parameter is not provided, the kickstart file will default
206 to /etc/cobbler/default.ks. This file is initially blank, meaning
207 default kickstarts are not automated "out of the box". Admins can
208 change the default.ks if they desire..
209 When using kickstart files, they can be placed anywhere on the
211 filesystem, but the recommended path is /var/lib/cobbler/kick‐
212 starts.
213 virt-file-size
215 (Virt-only) How large the disk image should be in Gigabytes. The
216 default is "5". This can be a comma seperated list (ex: "5,6,7")
217 to allow for multiple disks of different sizes depending on what is
218 given to --virt-path.
219 virt-ram
221 (Virt-only) How many megabytes of RAM to consume. The default is
222 512 MB.
223 virt-type
225 (Virt-only) Koan can install images using either Xen paravirt
226 ("xenpv") or QEMU/KVM ("qemu"). Choose one or the other strings to
227 specify, or values will default to attempting to find a compatible
228 installation type on the client system ("auto"). See the "koan"
229 manpage for more documentation. The default virt-type can be con‐
230 figured in the cobbler settings file such that this parameter does
231 not have to be provided.
232 virt-cpus
234 (Virt-only) How many virtual CPUs should koan give the virtual
235 machine? The default is 1.
236 virt-path
238 (Virt-only) Where to store the virtual image on the host system.
239 Except for advanced cases, this parameter can usually be omitted.
240 For disk images, the value is usually an absolute path to an exist‐
241 ing directory with an optional file name component. There is sup‐
242 port for specifying partitions "/dev/sda4" or volume groups "Vol‐
243 Group00", etc.
244 For multiple disks, seperate the values with commas such as "Vol‐
246 Group00,VolGroup00" or "/dev/sda4,/dev/sda5". Both those examples
247 would create two disks for the VM.
248 virt-bridge
250 (Virt-only) This specifies the default bridge to use for all sys‐
251 tems defined under this profile. If not specified, it will assume
252 the default value in the cobbler settings file, which as shipped in
253 the RPM is 'xenbr0'. If using KVM, this is most likely not cor‐
254 rect. You may want to override this setting in the system object.
255 Bridge settings are important as they define how outside networking
256 will reach the guest. For more information on bridge setup, see
257 the Cobbler Wiki, where there is a section describing koan usage.
258 repos
260 This is a space delimited list of all the repos (created with "cob‐
261 bler repo add" and updated with "cobbler reposync") that this pro‐
262 file can make use of during kickstart installation. For example,
263 an example might be --repos="fc6i386updates fc6i386extras" if the
264 profile wants to access these two mirrors that are already mirrored
265 on the cobbler server.
266 inherit
268 This is an advanced feature.
269 Profiles may inherit from other profiles in lieu of specifing
271 --distro. Inherited profiles will override any settings specified
272 in their parent, with the exception of --ksmeta (templating) and
273 --kopts (kernel options), which will be blended together.
274 Example: If profile A has --kopts="x=7 y=2", B inherits from A,
276 and B has --kopts="x=9 z=2", the actual kernel options that will be
277 used for B are "x=9 y=2 z=2".
278 Example: If profile B has --virt-ram=256 and A has --virt-ram of
280 512, profile B will use the value 256. Example: If profile A has
281 a --virt-file-size of 5 and B does not specify a size, B will use
282 the value from A.
283 server-override
285 This parameter should be useful only in select circumstances. If
286 machines are on a subnet that cannot access the cobbler server
287 using the name/IP as configured in the cobbler settings file, use
288 this parameter to override that server name. See also --dhcp-tag
289 for configuring the next server and DHCP informmation of the system
290 if you are also using Cobbler to help manage your DHCP configura‐
291 tion.
292 ADDING A SYSTEM
294 System records map a piece of hardware (or a virtual machine) with the
296 cobbler profile to be assigned to run on it. This may be thought of as
297 chosing a role for a specific system.
298 Note that if provisioning via koan and PXE menus alone, it is not
300 required to create system records, though they are useful when system
301 specific customizations are required. One such customization would be
302 defining the MAC address. If there is a specific role inteded for a
303 given machine, system records should be created for it.
304 cobbler system add --name=string --profile=string [--mac=macaddress]
306 [--ip=ipaddress] [--hostname=hostname] [--kopts=string]
307 [--ksmeta=string] [--kickstart=path] [--netboot-enabled=Y/N]
308 [--server-override=string]
309 Adds a cobbler System to the configuration. Arguments are specified as
311 per "profile add" with the following changes:
312 name
314 The system name works like the name option for other commands.
315 If the name looks like a MAC address or an IP, the name will
317 implicitly be used for either --mac or --ip of the first interface,
318 respectively. However, it's usually better to give a descriptive
319 name.
320 A system created with name "default" has special semantics. If a
322 default system object exists, it sets all undefined systems to PXE
323 to a specific profile. Without a "default" system name created,
324 PXE will fall through to local boot for unconfigured systems.
325 mac Specifying a mac address via --mac allows the system object to boot
327 via PXE. If the name of the cobbler system already looks like a
328 mac address, this is inferred from the system name and does not
329 need to be specified.
330 MAC addresses have the format AA:BB:CC:DD:EE:FF.
332 ip If cobbler is configured to generate a DHCP configuratition (see
334 advanced section), use this setting to define a specific IP for
335 this system in DHCP. Leaving off this parameter will result in no
336 DHCP management for this particular system.
337 Example: --ip=192.168.1.50
339 Note for Itanium users: this setting is always required for IA64
341 regardless of whether DHCP management is enabled.
342 If DHCP management is disabled, setting this parameter may still be
344 useful for record keeping, and it is also available in all kick‐
345 start templates, so it can be easily used for static IP configura‐
346 tion within kickstarts.
347 hostname
349 If using the DHCP configuration feature (see advanced section) with
350 dnsmasq, use this to define a hostname for the system to recieve
351 from DNS. If not using DHCP management or not using dnsmasq, this
352 field is treated as a descriptive comment and is basically ignored
353 other than being made available in templates.
354 Example: --hostname=mycomputer.example.com
356 --gateway and --subnet
358 If you are using static IP configurations, you may find it useful
359 to store gateway and subnet information inside of cobbler. These
360 variables are not used internally by cobbler, but are made avail‐
361 able in cobbler templates, which are described later in this docu‐
362 ment and on the Wiki. For DHCP configurations, these parameters
363 should be left blank.
364 --virt-bridge
366 (Virt-only) While --virt-bridge is present in the profile object
367 (see above), here it works on an interface by interface basis.
368 For instance it would be possible to have --virt-bridge0=xenbr0 and
369 --virt-bridge1=xenbr1. If not specified in cobbler for each inter‐
370 face, koan will use the value as specified in the profile for each
371 interface, which may not always be what is intended, but will be
372 sufficient in most cases.
373 --kickstart
375 While it is recommended that the --kickstart parameter is only used
376 within for the "profile add" command, there are scenarios when an
377 install base switching to cobbler may have kickstarts created on a
378 per-system basis (one kickstart for each system, nothing shared)
379 and may not want to immediately make use of the cobbler templating
380 system. This allows specifing a kickstart for use on a per-system
381 basis. Creation of a parent profile is still required. If the
382 kickstart is a filesystem location, it will still be treated as a
383 cobbler template.
384 --netboot-enabled
386 If set false, the system will be provisionable through koan but not
387 through standard PXE. This will allow the system to fall back to
388 default PXE boot behavior without deleting the cobbler system
389 object. The default value allows PXE.
390 --dhcp-tag
392 If you are setting up a PXE environment with multiple subnets/gate‐
393 ways, and are using cobbler to manage a DHCP configuration, you
394 will probably want this option.
395 By default, the dhcp tag for all systems is "default" and means
397 that in the DHCP template files the systems will expand out where
398 $insert_cobbler_systems_definitions is found in the DHCP template.
399 However, you may want certain systems to expand out in other places
400 in the file. Setting --dhcp-tag=subnet2 for instance, will cause
401 that system to expand out where $insert_cobbler_system_defini‐
402 tions_subnet2 is found, allowing you to insert directives to spec‐
403 ify different subnets (or other parameters) before the DHCP config‐
404 uration entries for those particular systems.
405 This is described further on the Cobbler Wiki.
407 --interface
409 By default flags like --ip, --mac, --dhcp-tag, --gateway, --subnet,
410 and --virt-bridge operation on the first network interface defined
411 for a system. Additional interfaces can be specified (0 through 7)
412 for use with the edit command.
413 Example:
415 cobbler system edit --name=foo --ip=192.168.1.50
417 --mac=AA:BB:CC:DD:EE:A0 cobbler system edit --name=foo --inter‐
418 face=2 --ip=192.168.1.51 --mac=AA:BB:CC:DD:EE:A1 cobbler system
419 report foo
420 NOTE: Additional interfaces can presently only be deleted via the
422 web interface.
423 ADDING A REPOSITORY TO MIRROR
425 Repository mirroring allows cobbler to mirror not only install trees
427 ("cobbler import" does this for you) but also optional packages, 3rd
428 party content, and even updates. Mirroring all of this content
429 locally on your network will result in faster, more up-to-date instal‐
430 lations and faster updates. If you are only provisioning a home setup,
431 this will probably be overkill, though it can be very useful for larger
432 setups (labs, datacenters, etc).
433 cobbler repo add --mirror=url --name=string [--rpmlist=list] [--cre‐
435 atrepo-flags=string] [--keep-updated=Y/N] [--priority=number]
436 [--arch=string] [--mirror-locally=Y/N]
437 mirror
439 The addresss of the yum mirror. This can be an rsync:// URL,
440 an ssh location, or a http:// or ftp:// mirror location.
441 Filesystem paths also work.
442 The mirror address should specify an exact repository to mirror
444 -- just one architecture and just one distribution. If you
445 have a seperate repo to mirror for a different arch, add that
446 repo seperately.
447 Here's an example of what looks like a good URL:
449 rsync://yourmirror.example.com/fedora-linux-core/updates/6/i386
451 (for rsync protocol) http://mirrors.ker‐
452 nel.org/fedora/extras/6/i386/ (for http://) user@yourmir‐
453 ror.example.com/fedora-linux-core/updates/6/i386 (for SSH)
454 Experimental support is also provided for mirroring RHN content
456 when you need a fast local mirror. The mirror syntax for this
457 is --mirror=rhn://channel-name and you must have entitlements
458 for this to work. This requires the cobbler server to be
459 installed on RHEL5 or later. You will also need a version of
460 yum-utils equal or greater to 1.0.4.
461 Additionally, if you are running yum 3.2.4 or later, you can
463 also automatically tell cobbler to mirror any yum repository
464 that the boot server itself is configured to use. This command
465 is "cobbler repo auto-add" and is also somewhat experimental.
466 name
468 This name is used as the save location for the mirror. If the
469 mirror represented, say, Fedora Core 6 i386 updates, a good
470 name would be "fc6i386updates". Again, be specific.
471 This name corresponds with values given to the --repos parame‐
473 ter of "cobbler profile add". If a profile has a --repos value
474 that matches the name given here, that repo can be automati‐
475 cally set up during provisioning (when supported) and installed
476 systems will also use the boot server as a mirror (unless
477 "yum_post_install_mirror" is disabled in the settings file).
478 By default the provisioning server will act as a mirror to sys‐
479 tems it installs, which may not be desirable for laptop config‐
480 urations, etc.
481 Distros that can make use of yum repositories during kickstart
483 include FC6 and later, RHEL 5 and later, and derivative distri‐
484 butions.
485 See the documentation on "cobbler profile add" for more infor‐
487 mation.
488 rpm-list
490 By specifying a space-delimited list of package names for
491 --rpm-list, one can decide to mirror only a part of a repo (the
492 list of packages given, plus dependencies). This may be help‐
493 ful in conserving time/space/bandwidth. For instance, when
494 mirroring FC6 Extras, it may be desired to mirror just cobbler
495 and koan, and skip all of the game packages. To do this, use
496 --rpm-list="cobbler koan".
497 This option only works for http:// and ftp:// repositories (as
499 it is powered by yumdownloader). It will be ignored for other
500 mirror types, such as local paths and rsync:// mirrors.
501 createrepo-flags
503 Specifies optional flags to feed into the createrepo tool,
504 which is called when "cobbler reposync" is run for the given
505 repository. The defaults are '-c cache'.
506 keep-updated
508 Specifies that the named repository should not be updated dur‐
509 ing a normal "cobbler reposync". The repo may still be
510 updated by name. See "cobbler reposync" below.
511 mirror-locally
513 When true, specifies that this yum repo is to be referenced
514 directly via kickstarts and not mirrored locally on the cobbler
515 server. Only http:// and ftp:// mirror urls are supported when
516 using --mirror-locally=1.
517 priority
519 Specifies the priority of the repository (the lower the number,
520 the higher the priority), which applies to installed machines
521 using the repositories that also have the yum priorities plugin
522 installed. The default priority for the plugin is 99, as is
523 that of all cobbler mirrored repositories.
524 arch
526 Specifies what architecture the repository should use. By
527 default the current system arch (of the server) is used, which
528 may not be desirable. Using this to override the default arch
529 allows mirroring of source repositories (using --arch=src).
530 yumopts
532 Sets values for additional yum options that the repo should use
533 on installed systems. For instance if a yum plugin takes a
534 certain parameter "alpha" and "beta", use something like
535 --yumopts="alpha=2 beta=3".
536 DISPLAYING CONFIGURATION ENTRIES
538 The following commands are usable regardless of how you are using
540 cobbler. "report" gives detailed configuration info. "list" just
541 lists the names of items in the configuration. Run these commands
542 to check how you have cobbler configured.
543 cobbler report
545 cobbler distro⎪profile⎪system⎪repo report [object-name]
547 cobbler list
549 Alternatively, you could look at the configuration files in
551 /var/lib/cobbler to see the same information.
552 DELETING CONFIGURATION ENTRIES
554 If you want to remove a specific object, use the remove command
556 with the name that was used to add it.
557 cobbler distro remove --name=string
559 cobbler profile remove --name=string
561 cobbler system remove --name=string
563 cobbler repo remove --name=string
565 EDITING
567 If you want to change a particular setting without doing an "add"
569 again, use the "edit" command, using the same name you gave when
570 you added the item. Anything supplied in the parameter list will
571 overwrite the settings in the existing object, preserving settings
572 not mentioned.
573 cobbler distro⎪profile⎪system⎪repo edit --name=string [parame‐
575 terlist]
576 COPYING
578 Objects can also be copied:
580 cobbler distro⎪profile⎪system⎪repo copy --name=oldname --new‐
582 name=newname
583 RENAMING
585 Objects can also be renamed, as long as other objects don't refer‐
587 ence them.
588 cobbler distro⎪profile⎪system⎪repo rename --name=oldname --new‐
590 name=newname
591 REPLICATING
593 Cobbler can replicate distro and profile data from a master cobbler
595 server.
596 cobbler replicate --master=cobbler.example.org
598 This will bring over all distro data for which it can find data in
600 /var/www/cobbler/ks_mirror can be found. It will also bring over
601 any default profiles for those distros. A default cobbler master
602 can be set in the settings file. Tree data must still be rsync'd
603 (or otherwise mirrored) manually.
604 REBUILDING CONFIGURATIONS
606 cobbler sync
608 Cobbler sync is used to repair or rebuild the contents /tftpboot or
610 /var/www/cobbler when something has changed behind the scenes. It
611 brings the filesystem up to date with the configuration as under‐
612 stood by cobbler.
613 Sync should be run whenever files in /var/lib/cobbler are manually
615 edited (which is not recommended except for the settings file) or
616 when making changes to kickstart files. In practice, this should
617 not happen often, though running sync too many times does not cause
618 any adverse effects.
619 If using cobbler to manage a DHCP and/or DNS server (see the
621 advanced section of this manpage), sync does need to be run after
622 systems are added to regenerate and reload the DHCP/DNS configura‐
623 tion.
624
626 IMPORT WORKFLOW
627 This example shows how to create a provisioning infrastructure from a
629 distribution mirror or DVD ISO. Then a default PXE configuration is
630 created, so that by default systems will PXE boot into a fully auto‐
631 mated install process for that distribution.
632 You can use a network rsync mirror, a mounted DVD location, or a tree
634 you have available via a network filesystem.
635 Import knows how to autodetect the architecture of what is being
637 imported, though to make sure things are named correctly, it's always a
638 good idea to specify --arch. For instance, if you import a distribu‐
639 tion named "fedora8" from an ISO, and it's an x86_64 ISO, specify
640 --arch=x86_64 and the distro will be named "fedora8-x86_64" automati‐
641 cally, and the right architecture field will also be set on the distri‐
642 bution object. If you are batch importing an entire mirror (containing
643 multiple distributions and arches), you don't have to do this, as cob‐
644 bler will set the names for things based on the paths it finds.
645 cobbler check
647 cobbler import --path=rsync://yourfavoritemirror.com/foo --name=rhel5
649 --arch=x86
650 # OR
652 cobbler import --path=/mnt/dvd --name=rhel5 --arch=x86_64
654 # OR (using an eternal NAS box without mirroring)
656 cobbler import --path=/path/where/filer/is/mounted --name=anyname
658 --available-as=nfs://nfs.example.org:/where/mounted/
659 # wait for mirror to rsync...
661 cobbler report
663 cobbler system add --name=default --profile=name_of_a_profile1
665 cobbler system add --name=AA:BB:CC:DD:EE:FF --profile=name_of_a_pro‐
667 file2
668 cobbler sync
670 NORMAL WORKFLOW
672 The following example uses a local kernel and initrd file (already
674 downloaded), and shows how profiles would be created using two differ‐
675 ent kickstarts -- one for a web server configuration and one for a
676 database server. Then, a machine is assigned to each profile.
677 cobbler check
679 cobbler distro add --name=rhel4u3 --kernel=/dir1/vmlinuz --ini‐
681 trd=/dir1/initrd.img
682 cobbler distro add --name=fc5 --kernel=/dir2/vmlinuz --ini‐
684 trd=/dir2/initrd.img
685 cobbler profile add --name=fc5webservers --distro=fc5-i386 --kick‐
687 start=/dir4/kick.ks --kopts="some‐
688 thing_to_make_my_gfx_card_work=42,some_other_parameter=foo"
689 cobbler profile add --name=rhel4u3dbservers --distro=rhel4u3 --kick‐
691 start=/dir5/kick.ks
692 cobbler system add --name=AA:BB:CC:DD:EE:FF --profile=fc5-webservers
694 cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=rhel4u3-dbservers
696 cobbler report
698 REPOSITORY MIRRORING WORKFLOW
700 The following example shows how to set up a repo mirror for two reposi‐
702 tories, and create a profile that will auto install those repository
703 configurations on provisioned systems using that profile.
704 cobbler check
706 # set up your cobbler distros here.
708 cobbler repo add --mirror=http://mirrors.ker‐
710 nel.org/fedora/core/updates/6/i386/ --name=fc6i386updates
711 cobbler repo add --mirror=http://mirrors.ker‐
713 nel.org/fedora/extras/6/i386/ --name=fc6i386extras
714 cobbler reposync
716 cobbler profile add --name=p1 --distro=existing_distro_name --kick‐
718 start=/etc/cobbler/kickstart_fc6.ks --repos="fc6i386updates
719 fc6i386extras"
720 VIRTUALIZATION
722 For Virt, be sure the distro uses the correct kernel (if paravirt) and
724 follow similar steps as above, adding additional parameters as desired:
725 cobbler distro add --name=fc7virt [options...]
727 Specify reasonable values for the Virt image size (in GB) and RAM
729 requirements (in MB):
730 cobbler profile add --name=virtwebservers --distro=fc7virt --kick‐
732 start=path --virt-file-size=10 --virt-ram=512 [...]
733 Define systems if desired. koan can also provision based on the pro‐
735 file name.
736 cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=virtwebservers
738 [...]
739 If you have just installed cobbler, be sure that the "cobblerd" service
741 is running and that port 25151 is unblocked.
742 See the manpage for koan for the client side steps.
744
746 PXE MENUS
747 Cobbler will automatically generate PXE menus for all profiles it has
749 defined. Running "cobbler sync" is required to generate and update
750 these menus.
751 To access the menus, type "menu" at the "boot:" prompt while a system
753 is PXE booting. If nothing is typed, the network boot will default to
754 a local boot. If "menu" is typed, the user can then choose and provi‐
755 sion any cobbler profile the system knows about.
756 If the association between a system (MAC address) and a profile is
758 already known, it may be more useful to just use "system add" commands
759 and declare that relationship in cobbler; however many use cases will
760 prefer having a PXE system, especially when provisioning is done at the
761 same time as installing new physical machines.
762 If this behavior is not desired, run "cobbler system add --name=default
764 --profile=plugh" to default all PXE booting machines to get a new copy
765 of the profile "plugh". To go back to the menu system, run "cobbler
766 system remove --name=default" and then "cobbler sync" to regenerate the
767 menus.
768 When using PXE menu deployment exclusively, it is not neccessary to
770 make cobbler system records, although the two can easily be mixed.
771 Additionally, note that all files generated for the pxe menu configura‐
773 tions are templatable, so if you wish to change the color scheme or
774 equivalent, see the files in /etc/cobbler.
775 KICKSTART TEMPLATING
777 The --ksmeta options above require more explanation.
779 If and only if --kickstart options reference filesystem URLs, --ksmeta
781 allows for templating of the kickstart files to achieve advanced func‐
782 tions. If the --ksmeta option for a profile read --ksmeta="foo=7
783 bar=llama", anywhere in the kickstart file where the string "$bar"
784 appeared would be replaced with the string "llama".
785 To apply these changes, "cobbler sync" must be run to generate custom
787 kickstarts for each profile/system.
788 For NFS and HTTP kickstart URLs, the "--ksmeta" options will have no
790 effect. This is a good reason to let cobbler manage your kickstart
791 files, though the URL functionality is provided for integration with
792 legacy infrastructure, possibly including web apps that already gener‐
793 ate kickstarts.
794 Templated kickstart files are processed by the templating program/pack‐
796 age Cheetah, so anything you can do in a Cheetah template can be done
797 to a kickstart template. Learn more at http://www.cheetahtem‐
798 plate.org/learn.html
799 When working with Cheetah, be sure to escape any shell macros that look
801 like "$(this)" with something like "\$(this)" or errors may show up
802 during the sync process.
803 KICKSTART SNIPPETS
805 Anywhere a kickstart template mentions SNIPPET::snippet_name, the file
807 named /var/lib/cobbler/snippets/snippet_name (if present) will be
808 included automatically in the kickstart template. This serves as a way
809 to recycle frequently used kickstart snippets without duplication.
810 Snippets can contain templating variables, and the variables will be
811 evaluated according to the profile and/or system as one would expect.
812 KICKSTART VALIDATION
814 To check for potential errors in kickstarts, prior to installation, use
816 "cobbler validateks". This function will check all profile and system
817 kickstarts for detectable errors. Since pykickstart is not future-Ana‐
818 conda-version aware, there may be some false positives. It should be
819 noted that "cobbler validateks" runs on the rendered kickstart output,
820 not kickstart templates themselves.
821 DHCP MANAGEMENT
823 Cobbler can optionally help you manage DHCP server. This feature is
825 off by default.
826 Choose either "management = isc_and_bind" in /etc/cobbler/dhcp.template
828 or "management = "dnsmasq" in /etc/cobbler/modules.conf. Then set
829 "manage_dhcp" to 1 in /etc/cobbler/settings.
830 This allows DHCP to be managed via "cobbler system add" commands, when
832 you specify the mac address and IP address for systems you add into
833 cobbler.
834 Depending on your choice, cobbler will use /etc/cobbler/dhcpd.template
836 or /etc/cobbler/dnsmasq.template as a starting point. This file must
837 be user edited for the user's particular networking environment. Read
838 the file and understand how the particular app (ISC dhcpd or dnsmasq)
839 work before proceeding.
840 If you already have DHCP configuration data that you would like to pre‐
842 serve (say DHCP was manually configured earlier), insert the relevant
843 portions of it into the template file, as running "cobbler sync" will
844 overwrite your previous configuration.
845 NOTE: Itanium systems names also need to be assigned to a distro that
847 was created with the "--arch=ia64" parameter. If you have Itanium sys‐
848 tems, you must (for now) choose 'dhcp_isc' for /etc/cobbler/mod‐
849 ules.conf and manage_dhcp in the /etc/cobbler/settings file, and are
850 required to use --ip when creating the system object in order for those
851 systems to PXE. This is due to an elilo limitation.
852 By default, the DHCP configuration file will be updated each time "cob‐
854 bler sync" is run, and not until then, so it is important to remember
855 to use "cobbler sync" when using this feature.
856 If omapi_enabled is set to 1 in /etc/cobbler/settings, the need to sync
858 when adding new system records can be eliminated.
859 DNS CONFIGURATION MANAGEMENT
861 Cobbler can optionally manage DNS configuration using BIND and dnsmasq.
863 Choose either "management = isc_and_bind" or "management = dnsmasq" in
865 /etc/cobbler/modules.conf and then enable manage_dns in /etc/cob‐
866 bler/settings.
867 This feature is off by default. If using BIND, you must define the
869 zones to be managed with the options 'manage_forward_zones' and 'man‐
870 age_reverse_zones'. (See the Wiki for more information on this).
871 If using BIND, Cobbler will use /etc/cobbler/bind.template and
873 /etc/cobbler/zone.template as a starting point for the named.conf and
874 individual zone files, respectively. You may drop zone-specific tem‐
875 plate files in /etc/cobbler/zone_templates/name-of-zone which will
876 override the default. These files must be user edited for the user's
877 particular networking environment. Read the file and understand how
878 BIND works before proceeding.
879 If using dnsmasq, the template is /etc/cobbler/dnsmasq.template. Read
881 this file and understand how dnsmasq works before proceeding.
882 All managed files (whether zone files and named.conf for BIND, or dns‐
884 masq.conf for dnsmasq) will be updated each time ``cobbler sync'' is
885 run, and not until then, so it is important to remember to use ``cob‐
886 bler sync'' when using this feature.
887 SERVICE DISCOVERY (AVAHI)
889 If the avahi-tools package is installed, cobblerd will broadcast it's
891 presence on the network, allowing it to be discovered by koan with the
892 koan --server=DISCOVER parameter.
893 IMPORTING TREES
895 Cobbler can auto-add distributions and profiles from remote sources,
897 whether this is a filesystem path or an rsync mirror. This can save a
898 lot of time when setting up a new provisioning environment. Import is
899 a feature that many users will want to take advantage of, and is very
900 simple to use.
901 After an import is run, cobbler will try to detect the distribution
903 type and automatically assign kickstarts. By default, it will provi‐
904 sion the system by erasing the hard drive, setting up eth0 for dhcp,
905 and using a default password of "cobbler". If this is undesirable,
906 edit the kickstart files in /etc/cobbler to do something else or change
907 the kickstart setting after cobbler creates the profile.
908 Mirrored content is saved automatically in /var/www/cobbler/ks_mirror.
910 Example: cobbler import --mirror=rsync://mirrorserver.exam‐
912 ple.com/path/ --name=fedora --arch=x86
913 Example2: cobbler import --mirror=root@192.168.1.10:/stuff --name=bar
915 Example3: cobbler import --mirror=/mnt/dvd --name=baz --arch=x86_64
917 Example4: cobbler import --mirror=/path/to/stuff --name=glorp
919 Example5: cobbler import --path=/path/where/filer/is/mounted
921 --name=anyname --available-as=nfs://nfs.example.org:/where/mounted/
922 Once imported, run a "cobbler list" or "cobbler report" to see what
924 you've added.
925 By default, the rsync operations will exclude PPC content, debug RPMs,
927 and ISO images -- to change what is excluded during an import, see
928 /etc/cobbler/rsync.exclude.
929 Note that all of the import commands will mirror install tree content
931 into /var/www/cobbler unless a network accessible location is given
932 with --available-as. --available-as will be primarily used when
933 importing distros stored on an external NAS box, or potentially on
934 another partition on the same machine that is already accessible via
935 http:// or ftp://.
936 For import methods using rsync, additional flags can be passed to rsync
938 with the option --rsync-flags.
939 Should you want to force the usage of a specific cobbler kickstart tem‐
941 plate for all profiles created by an import, you can feed the option
942 --kickstart to import, to bypass the built-in kickstart auto-detection.
943 DEFAULT PXE BOOT BEHAVIOR
945 What happens when PXE booting a system when cobbler has no record of
947 the system being booted?
948 By default, cobbler will configure PXE to boot to the contents of
950 /etc/cobbler/default.pxe, which (if unmodified) will just fall through
951 to the local boot process. Administrators can modify this file if they
952 like to change that behavior.
953 An easy way to specify a default cobbler profile to PXE boot is to cre‐
955 ate a system named "default". This will cause /etc/cobbler/default.pxe
956 to be ignored. To restore the previous behavior do a "cobbler system
957 remove" on the "default" system.
958 cobbler system add --name=default --profile=boot_this
960 cobbler system remove --name=default
962 REPO MANAGEMENT
964 This has already been covered a good bit in the command reference sec‐
966 tion.
967 Yum repository management is an optional feature, and is not required
969 to provision through cobbler. However, if cobbler is configured to
970 mirror certain repositories, it can then be used to associate profiles
971 with those repositories. Systems installed under those profiles will
972 then be autoconfigured to use these repository mirrors in
973 /etc/yum.repos.d, and if supported (Fedora Core 6 and later) these
974 repositories can be leveraged even within Anaconda. This can be useful
975 if (A) you have a large install base, (B) you want fast installation
976 and upgrades for your systems, or (C) have some extra software not in a
977 standard repository but want provisioned systems to know about that
978 repository.
979 Make sure there is plenty of space in cobbler's webdir, which defaults
981 to /var/www/cobbler.
982 cobbler reposync
984 Cobbler reposync is the command to use to update repos as configured
986 with "cobbler repo add". Mirroring can take a long time, and usage of
987 cobbler reposync prior to cobbler sync is needed to ensure provisioned
988 systems have the files they need to actually use the mirrored reposito‐
989 ries. If you just add repos and never run "cobbler reposync", the
990 repos will never be mirrored. This is probably a command you would
991 want to put on a crontab, though the frequency of that crontab and
992 where the output goes is left up to the systems administrator.
993 For those familiar with yum's reposync, cobbler's reposync is (in most
995 uses) a wrapper around the yum command. Please use "cobbler reposync"
996 to update cobbler mirrors, as yum's reposync does not perform all
997 required steps. Also cobbler adds support for rsync and SSH locations,
998 where as yum's reposync only supports what yum supports (http/ftp).
999 If you ever want to update a certain repository you can run:
1001 cobbler reposync --only="reponame1" ...
1003 When updating repos by name, a repo will be updated even if it is set
1005 to be not updated during a regular reposync operation (ex: cobbler repo
1006 edit --name=reponame1 --keep-updated=0).
1007 Note that if a cobbler import provides enough information to use the
1009 boot server as a yum mirror for core packages, cobbler can set up kick‐
1010 starts to use the cobbler server as a mirror instead of the outside
1011 world. If this feature is not desirable, it can be turned on by set‐
1012 ting yum_post_install_mirror to 0 in /etc/settings (and rerunning "cob‐
1013 bler sync"). You should disable this feature if machines are provi‐
1014 sioned on a different VLAN/network than production, or if you are pro‐
1015 visioning laptops that will want to acquire updates on multiple net‐
1016 works.
1017 PXE BOOT LOOP PREVENTION
1019 If you have your machines set to PXE first in the boot order (ahead of
1021 hard drives), change the "pxe_just_once" flag in /etc/cobbler/settings
1022 to 1. This will set the machines to not PXE on successive boots once
1023 they complete one install. To re-enable PXE for a specific system, run
1024 the following command:
1025 cobbler system edit --name=name --netboot-enabled=1
1027 KICKSTART TRACKING
1029 Cobbler knows how to keep track of the status of kickstarting machines.
1031 cobbler status
1033 Using the status command will show when cobbler thinks a machine
1035 started kickstarting and when it last requested a file. This is a good
1036 way to track machines that may have gone interactive during kickstarts.
1037 Cobbler will also make a special request in the post section of the
1038 kickstart to signal when a machine is finished kickstarting.
1039 To use this feature, the kickstart tree files need to be served via a
1041 http://server/cblr/... URL, which happens automatically when using the
1042 "cobbler import" command to pull in a kickstart tree from an rsync mir‐
1043 ror.
1044 If kickstart trees are somewhere else, one can still benefit from the
1046 kickstart tracking feature by adding a symlink to /var/www/cob‐
1047 bler/localmirror/distroname will allow the kickstarts to be served
1048 through the tracking URL mentioned above. Be sure to use the
1049 http://server/cblr/ URL to point to the kickstart tree for each distro
1050 you want to track.
1051 Note that kickstart tracking support using syslog requires an Anaconda
1053 that supports syslog forwarding. RHEL5 is good, as is FC6 and later.
1054 URL tracking currently requires python2.3 or higher on the server for
1055 the mod_python piece to work. This will likely be improved later to
1056 better support older distros acting as a cobbler server.
1057 TWEAKING
1059 Enterprising users can edit the files in /var/lib/cobbler directly ver‐
1061 sus using the command line. The repair mechanism for user error here
1062 is to delete the files in /var/lib/cobbler. There are also a few con‐
1063 figuration files in /etc/cobbler that can be edited.
1064 Running "cobbler sync" is required to apply any changes that are made
1066 manually.
1067 TRIGGERS
1069 Triggers provide a way to integrate cobbler with arbitrary 3rd party
1071 software without modifying cobbler's code. When adding a distro, pro‐
1072 file, system, or repo, all scripts in /var/lib/cobbler/triggers/add are
1073 executed for the particular object type. Each particular file must be
1074 executable and it is executed with the name of the item being added as
1075 a parameter. Deletions work similarly -- delete triggers live in
1076 /var/lib/cobbler/triggers/delete. Order of execution is arbitrary, and
1077 cobbler does not ship with any triggers by default.
1078 API
1080 Cobbler also makes itself available as a Python API for use by higher
1082 level management software. Learn more at http://cobbler.et.redhat.com
1083 WEB USER INTERFACE
1085 Most of the day-to-day actions in cobbler's command line can be per‐
1087 formed in Cobbler's Web UI. To enable and access the WebUI, see the
1088 following documentation:
1089 https://hosted.fedoraproject.org/projects/cobbler/wiki/CobblerWebUi
1091 BOOT CD
1093 Cobbler can build all of it's profiles into a bootable CD image using
1095 the "cobbler buildiso" command. This allows for PXE-menu like bringup
1096 of bare metal in evnvironments where PXE is not possible. Another more
1097 advanced method is described in the koan manpage, though this method is
1098 easier and sufficient for most applications.
1099
1101 cobbler's command line returns a zero for success and non-zero for
1102 failure.
1103
1105 Cobbler has a mailing list for user and development-related ques‐
1106 tions/comments at et-mgmt-tools@redhat.com.
1107 IRC channel: irc.freenode.net (#cobbler)
1109 Official web site: http://cobbler.et.redhat.com/
1111 Wiki and user contributed content: https://hosted.fedorapro‐
1113 ject.org/projects/cobbler/
1114
1116 Michael DeHaan <mdehaan@redhat.com>
1117 2008-06-06 COBBLER(1)