Manual pages › System administration commands (1M)
bkreg(1M)
change or display the contents of a backup register
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
NAME · SYNOPSIS · DESCRIPTION · DIAGNOSTICS · EXAMPLES · FILES · SEE ALSO
NAME
bkreg - change or display the contents of a backup register
SYNOPSIS
bkreg
-p period [-w cweek] [-t table]
bkreg
-a tag -o orig -c weeks:days|demand -d ddev -m
method|migration
[-b moptions] [-t table] [-D depend] [-P prio]
bkreg
-e tag [-o orig] [-c weeks:days|demand] [-m
method|migration] [-d ddev] [-t table] [-b moptions]
[-D depend] [-P prio]
bkreg
-r tag [-t table]
bkreg
[-A|-O|-R] [-hsv] [-t table] [-c weeks[:days]|demand]
bkreg
-C fields [-hv] [-t table] [-c weeks[:days]|demand] [-f
c]
DESCRIPTION
A backup register is a file containing descriptions of backup operations to be performed on a UNIX system. The default backup register is located in /etc/bkup/bkreg.tab. Other backup registers may be created. The bkreg command may be executed only by a user with superuser privilege. Each entry in a backup register describes backup operations to be performed on a given disk object (called the originating object) for some set of days and weeks during a rotation period. There may be several register entries for an object, but only one entry may specify backup operations for an object on a specific day and week of the rotation period. The entry describes the object, the backup method to be used to archive the object, and the destination volumes to be used to store the archive. Each entry has a unique tag that identifies it. Tags must conform to file naming conventions.
Rotation Period
Backups are performed in a rotation period specified in weeks. When the end of a rotation period is reached, a new period begins. Rotation periods begin on Sundays. The default rotation period is one week.
Originating Objects
An originating object is either a raw data partition or a filesystem. An originating object is described by its originating object name, its device name, and optional volume labels. Several backup operations for different originating objects may be active concurrently by specifying priorities and dependencies. During a backup session, higher priority backup operations are attempted before lower priority backup operations. All backup operations of a given priority may proceed concurrently unless dependencies are specified. If one backup is declared to be dependent on others, it will not be started until all of its antecedents have completed successfully.
Destination Devices
Each backup archive is written to a set of storage volumes inserted into a destination device. A destination device can have destination device group, a destination device name, media characteristics, and volume labels. Default characteristics for a medium (as specified in the device table) may be overridden (see the ``Device Management'' chapter in the System Administrator's Guide).
Backup Methods
An originating object is backed up to a destination device archive using a method. The method determines the amount of information backed up and the representation of that information. Different methods may be used for a given originating object on different days of the rotation. Each method accepts a set of options that are specific to the method. Several default methods are provided with the Backup service. Others methods may be added by a UNIX system site. For descriptions of the default methods, see incfile(1M), ffile(1M), fdisk(1M), fimage(1M), and fdp(1M). A backup archive may be migrated to a different destination by specifying migration as the backup method. The device name of the originating object for a migration must have been the destination device for a previously successful backup operation. This form of backup does not re-archive the originating object. It copies an archive from one destination to another, updating the backup service's databases so that restores can still be done automatically.
Register Validations
There are items in a single backup register entry and items across register entries that must be consistent for the backup service to conduct a backup session correctly. Some of these consistencies are checked at the time the backup register is created or changed. Others can be checked only at the time the backup register is used by backup(1M). See backup(1M) for a complete list of validations.
Modes
The bkreg command has two modes: changing the contents of a backup register and displaying the contents of a backup register.
Changing Contents
bkreg -p
changes the rotation period for a backup register.
The default rotation period is one week.
bkreg -a
adds an entry to a backup register. This option requires other options to be specified. These are listed below under Options.
bkreg -e
edits an existing entry in a backup register.
bkreg -r
removes an existing entry from a backup register.
Displaying Contents
bkreg -C
produces a customized display of the contents of a
backup register.
bkreg [-A|-R|-O]
produces a summary display of the contents of a backup register.
Options
-a Adds a new entry to the default backup register. Options required with -a are: tag, originating device, weeks:days, destination device, and method. If other options are not specified, the following defaults are used: the default backup register is used, no method options are specified, the priority is 0, and no dependencies exist between entries.
-b moptions
Each backup method supports a specific set of options that modify its behavior. moptions is specified as a list of options that are blank-separated and enclosed in quotes. The argument string provided here is passed to the method exactly as entered, without modification. For lists of valid options, see ``The Backup Service'' chapter in the System Administrator's Guide and the following entries in this book: fdisk(1M), fdp(1M), ffile(1M), fimage(1M), and incfile(1M).
-c weeks:days|demand
Sets the week(s) and day(s) of the rotation period
during which a backup entry should be performed or for
which a display should be generated.
weeks is a set of numbers including 1 and 52. The
value of weeks cannot be greater than the value of
-pperiod. weeks is specified as a combination of lists
or ranges (either comma-separated or blank-separated
and enclosed in quotes). An example set of weeks is
``1 3-10,13''
indicating the first week, each of the third through
tenth weeks, and the thirteenth week of the rotation
period.
days is either a set of numbers between 0 (Sunday) and 6 (Saturday), or a set of abbreviations between s (Sunday) and sa (Saturday). In addition, days are specified as a combination of lists or ranges (either comma-separated or blank-separated and enclosed in quotes).
demand indicates that an entry is used only when explicitly requested by
backup -c demand
-d ddev
Specifies ddev as the destination device for the backup
operation. ddev is of the form:
[dgroup][:[ddevice][:dchar][:dmname]]
where either dgroup or ddevice must be specified and dchar and dmname are optional. (Both dgroup and ddev may be specified together.) Colons delineate field boundaries and must be included as indicated above.
dgroup is the device group for the destination device. [See devgroup.tab(4).] If omitted, ddevice must be specified.
ddevice is the device name of a specific destination device. [See device.tab(4).] If omitted, dgroup must be specified and any available device in dgroup may be used.
dchar describes media characteristics. If specified, they override the default characteristics for the dev- ice and group. dchar is of the form: keyword=value
where keyword is a valid device characteristic keyword (as it appears in the device table.) dchar entries may be separated by commas or blanks. If separated by blanks, the entire string of arguments to ddev must be enclosed in quotes.
dlabels is a list of volume names of the destination volumes. The list of dlabels must be either comma-separated or blank-separated. If blank-separated, the entire ddev argument must be surrounded by quotes. Each dlabel corresponds to a volumename specified on the labelit command. If dlabels is omitted, backup and restore do not validate the volume labels on this entry.
-e Edits an existing entry. If any of the options -b, -c, -d, -m, -o, -D, or -P are present, they replace the current settings for the specified entry in the register.
-f c Overrides the default output field separator. c is the
character that will appear as the field separator on
the display output. The default output field separator
is colon (:).
-h Suppresses headers when generating displays.
-m method|migration
Performs the backup using the specified method. Default methods are: incfile, ffile, fdisk, fimage, and fdp. If the method to be used is not a default method, it must appear as the executable file in the standard method directory /etc/bkup/method. migration indicates that the value of orig (following the -o option) matches the value of ddev during a prior backup operation. The originating object is not rearchived; it is simply copied to the location specified by ddev (following the -d option). The backup history (if any) and tables of contents (if any) are updated to reflect the changed destination for the original archive.
-o orig
Specifies orig as the originating object for the backup
operation. orig is specified in the following format:
oname:odevice[:omname]
where oname is the name of an originating object. For
file system partitions, it is the nodename on which the
file system is usually mounted, mount. For data parti-
tions, it is any valid path name. This value is pro-
vided to the backup method and validated by backup.
The default data partition backup methods, fdp and
fdisk, do not validate this name.
odevice is the device name for the originating object. In all cases, it is a raw disk partition device name.
For AT&T 3B2 computers, this name is specified in the following format: /dev/rdsk/c?d?s?.
olabel is the volume label for the originating object. For file system partitions, it corresponds to the volumename displayed by the labelit command. A data partition may have an associated volume name that appears nowhere except on the outside of the volume (where it is taped); getvol may be used to have an operator validate the name.
On AT&T 3B2 computers, the special data partition /dev/rdsk/c?d?s6 names an entire disk and is used when disk formatting or repartitioning is done to reference the disk's volume table of contents (VTOC). [See fmthard(1M) and prtvtoc(1M).] backup validates this special full disk partition with the disk volume name specified when the disk was partitioned. [See fmthard(1M).] If the disk volume name is omitted, backup does not validate the volume labels for this originating object.
-p period
Sets the rotation period (in weeks) for the backup register to period. The minimum value is 1; the maximum value is 52. By default the current week of the rotation is set to 1.
-r Removes the specified entries from the register.
-s Suppresses wrap-around behavior when generating
displays. Normal behavior is to wrap long values
within each field.
-t table
Uses table instead of the default register, bkreg.tab.
-v Generates displays using (vertical) columns instead of (horizontal) rows. This allows more information to be displayed without encountering problems displaying long lines.
-w cweek
Overrides the default behavior by setting the current week of the rotation period to cweek. cweek is an integer between 1 and the value of period. The default is 1.
-A Displays a report describing all fields in the register. The display produced by this option is best suited as input to a filter, since in horizontal mode it produces extremely long lines.
-C fields
Generates a display of the contents of a backup register, limiting the display to the specified fields. The output is a set of lines, one per register entry. Each line consists of the desired fields, separated by a field separator character. fields is a list of field names (either comma-separated or blank-separated and enclosed in quotes) for the fields desired. The valid field names are period, cweek, tag, oname, odevice, olabel, weeks, days, method, moptions, prio, depend, dgroup, ddevice, dchar, and dlabel.
-D depend
Specifies a set of backup operations that must be completed successfully before this operation may begin. depend is a list of tag(s) (either comma-separated or blank-separated and enclosed in quotes) naming the antecedent backup operations.
-f c Overrides the default output field separator. c is the
character that will appear as the field separator on
the display output. The default output field separator
is colon (":").
-O Displays a summary of all originating objects with entries in the register.
-P prio
Sets a priority of prio for this backup operation. The default priority is 0; the highest priority is 100. All backup operations with the same priority may run simultaneously, unless the priority is 0. All backups with priority 0 run sequentially in an unspecified order.
-R Displays a summary of all destination devices with entries in the register.
DIAGNOSTICS
The exit codes for bkreg are the following:
0 = the task completed successfully
1 = one or more parameters to bkreg are invalid
2 = an error has occurred, causing bkreg to fail to
complete all portions of its task
Errors are reported on standard error if any of the following occurs:
1. The tag specified in bkreg -e or bkreg -r does not exist in the backup register.
2. The tag specified in bkreg -a already exists in the register.
EXAMPLES
Example 1:
bkreg -p 15 -w 3
establishes a 15-week rotation period in the default backup register and sets the current week to the 3rd week of the rotation period. Example 2:
bkreg -a acct5 -t wklybu.tab \
-o /usr:/dev/rdsk/c1d0s2:usr -c "2 4-6 8 10:0,2,5" \
-m incfile -b -txE \
-d diskette:capacity=1404:acctwkly1,acctwkly2,acctwkly3 \
adds an entry named acct5 to the backup register named
wklybu.tab. If wklybu.tab does not already exist, it will
be created. The originating object to be backed up is the
/usr file system on the /dev/rdsk/c1d0s2 device which is
known as usr. The backup will be performed each Sunday,
Tuesday, and Friday of the second, fourth through sixth,
eighth, and tenth weeks of the rotation period using the
incfile (incremental file) method. The method options
specify that a table of contents will be created on addi-
tional media instead of in the backup history log, the
exception list is to be ignored, and an estimate of the
number of volumes for the archive is to be provided before
performing the backup. The backup will be done to the next
available diskette device using the three diskette volumes
acctwkly1, acctwkly2, and acctwkly3. These volumes have a
capacity of 1404 blocks each.
Example 3:
bkreg -e services2 -t wklybu.tab \
-o /back:/dev/rdsk/c1d0s8:back -m migration \
-c demand -d ctape:/dev/rdsk/c4d0s3 \
changes the specifications for the backup operation named services2 on the backup table wklybu.tab so that whenever the command backup -c demand is executed, the backup that was performed to the destination device back:dev/rdsk/c1d0s2:back will be migrated from that device (now serving as the originating device) to a cartridge tape.
Example 4:
bkreg -e pubsfri -P 10 -D develfri,marketfri,acctfri
changes the priority level for the backup operation named pubsfri to 10 and makes this backup operation dependent on the three backup operations develfri, marketfri, and acctfri. The pubsfri operation will be done only after all backup operations with priorities greater than 10 have begun and after the develfri, marketfri, and acctfri operations have been completed successfully.
Example 5:
bkreg -c 1-8:0-6
provides the default display of the contents of the default backup register, for all weekdays for the first through eighth weeks of the rotation period. The information in the register will be displayed in the following format:
Rotation Period = 10 Current Week = 4 Originating Device: / /dev/root Tag Weeks Days Method Options Pri Dgroup - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - rootdai 1-8 1-6 incfile diskette rootsp 1-8 0 ffile -bxt 20 ctape Originating Device: /usr /dev/dsk/c1d0s2 Tag Weeks Days Method Options Pri Dgroup - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - usrdai 1-8 1-5 incfile diskette usrsp 1-8 0 ffile -bxt 15 ctape
FILES
/etc/bkup/method/*
/etc/bkup/bkreg.tab
describes the backup policy established by
the administrator
/etc/dgroup.tab
lists logical groupings of devices as deter-
mined by the administrator
/etc/device.tab
describes specific devices and their attri-
butes
SEE ALSO
backup(1M), fdisk(1M), fdp(1M), incfile(1M), ffile(1M), fimage(1M), fmthard(1M), getvol(1M), labelit(1M), mkfs(1M), mount(1M), prtvtoc(1M), restore(1M)