1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM 'global.entities'>
10 <!-- lifted from troff+man by doclifter -->
11 <refentry id='amlabel.8'>
14 <refentrytitle>amlabel</refentrytitle>
15 <manvolnum>8</manvolnum>
21 <refname>amlabel</refname>
22 <refpurpose>label an Amanda tape</refpurpose>
29 <!-- body begins here -->
32 <command>amlabel</command>
33 <arg choice='opt'><option>--barcode <replaceable>barcode</replaceable></option></arg>
34 <arg choice='opt'><option>--meta <replaceable>meta-label</replaceable></option></arg>
35 <arg><option>--assign</option></arg>
36 <arg><option>-f</option></arg>
38 &configoverride.synopsis;
39 <arg choice='plain'><replaceable>config</replaceable></arg>
40 <arg choice='opt'><replaceable>label</replaceable></arg>
41 <arg choice='opt'>slot <replaceable>slot</replaceable></arg>
45 <refsect1><title>DESCRIPTION</title>
47 <para>This command applies a label to an Amanda volume, erasing the volume in
50 <para>Amanda uses labels to identify volumes: <manref name="amdump" vol="8" />
51 and <manref name="amflush" vol="8" /> verify the label before writing to make
52 sure the proper volume is loaded, and the recovery programs use the label to
53 ensure they are reading the data they expect.</para>
55 <para>If no <arg choice="opt"><replaceable>slot</replaceable></arg> and no <arg choice="opt"><replaceable>barcode</replaceable></arg> is given,
56 then <command>amlabel</command> labels the tape in the current slot of the
57 default changer. If a slot is given, it labels the volume in that slot. If a barcode is given, it labels the volume with that barcode.
58 <emphasis remap='I'>Label</emphasis> may be any string that does not contain
59 whitespace and that matches the <emphasis remap='B'>labelstr</emphasis> (see
60 <manref name="amanda.conf" vol="5" />).</para>
62 <para>If <arg choice="opt"><replaceable>label</replaceable></arg> is not given, an autolabel is
63 generated, see <emphasis remap='B'>autolabel</emphasis> in <manref name="amanda.conf" vol="5"/>.</para>
65 <para>If <arg><option>--assign</option></arg> is given, the barcode and meta-label are assigned to the label without labeling the volume. The label must already be in the tapelist file.</para>
66 <para>This command also appends the new volume to the &tapelist; file, so that
67 they will be used in the order they are labeled (depending on the taperscan in
68 use — see <manref name="amanda-taperscan" vol="7" />).</para>
70 <para>As a precaution, <command>amlabel</command> will not write a label if the
71 volume already contains an active label or if the label specified is on an
72 active tape. The <arg choice="opt">-f</arg> (force) flag bypasses these
76 <refsect1><title>OPTIONS</title>
77 <variablelist remap='TP'>
80 <term><option>--barcode <replaceable>barcode</replaceable></option></term>
82 <para>With <arg choice="opt">--assign</arg>, assign the barcode to the label.
83 Without <arg choice="opt">--assign</arg>, label the volume with that barcode.</para>
88 <term><option>--meta <replaceable>meta-label</replaceable></option></term>
90 <para>Assign the meta label to the label after labeling the volume.</para>
95 <term><option>--assign</option></term>
97 <para>Assign the barcode or meta-label to the label without labeling the volume. The label must already be in the tapelist file.</para>
102 <term><option>-f</option></term>
104 <para>Force the label operation; see above</para>
108 &version.varlistentry;
109 &configoverride.varlistentry;
114 <refsect1><title>EXAMPLE</title>
115 <para>Write an Amanda label with the string "DMP000" on
116 the current volume:</para>
119 % amlabel daily DMP000
122 <para>Label the tape in slot 3 of the changer with the label
123 "DMP003":</para>
126 % amlabel daily DMP003 slot 3
130 <refsect1><title>MESSAGES</title>
131 <variablelist remap='TP'>
135 <term>Label '<replaceable>label</replaceable>' doesn't match labelstr
136 '<replaceable>labelstr</replaceable>'</term>
138 <listitem><para>The given label does not match the configured labelstr. Even
139 with <option>-f</option>, this is an error.</para></listitem>
144 <term>Label '<replaceable>label</replaceable>' already on a volume</term>
146 <listitem><para>The given label is already on another volume in the tapelist, and
147 Amanda will not write it to this volume unless forced.</para></listitem>
152 <term>Found label '<replaceable>label</replaceable>', but it is not from
153 configuration <replaceable>config</replaceable>.</term>
155 <listitem><para>The label <command>amlabel</command> found on the volume does
156 not match this configuration's <emphasis remap='B'>labelstr</emphasis>, so it
157 is probably part of a different Amanda configuration. Amanda will not
158 overwrite the label unless it is forced.</para> </listitem>
163 <term>Volume with label '<emphasis remap='I'>label</emphasis>' contains
164 data from this configuration.</term>
166 <listitem> <para>The label <command>amlabel</command> found on the volume
167 still has valid data on it and Amanda will not overwrite it unless
168 forced. Note that this does not distinguish between active and inactive
169 volumes.</para></listitem>
180 <manref name="amanda.conf" vol="5"/>
181 <manref name="tapelist" vol="5"/>
182 <manref name="amanda-taperscan" vol="7"/>
183 <manref name="amdump" vol="8"/>,
184 <manref name="amflush" vol="8"/>