c8f1e6687e
OBS-URL: https://build.opensuse.org/request/show/482515 OBS-URL: https://build.opensuse.org/package/show/Archiving/dump?expand=0&rev=17
442 lines
11 KiB
Groff
442 lines
11 KiB
Groff
.\" Copyright (c) 1983, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.TH ERMT 1 "version __VERSION__ of __DATE__" BSD "System management commands"
|
|
.SH NAME
|
|
ermt \- remote magtape protocol module with transparent encryption support
|
|
.SH SYNOPSIS
|
|
.B ermt
|
|
.SH DESCRIPTION
|
|
.B Ermt
|
|
is a program used by the remote
|
|
.BR dump (8),
|
|
.BR restore (8)
|
|
.BR cpio (1)
|
|
or
|
|
.BR tar (1)
|
|
programs in manipulating a magnetic tape drive through an interprocess
|
|
communication connection.
|
|
.B Ermt
|
|
is normally started up with an
|
|
.BR ssh (1)
|
|
.BR rexec (3)
|
|
or
|
|
.BR rcmd (3)
|
|
call.
|
|
.PP
|
|
The
|
|
.B ermt
|
|
program accepts requests specific to the manipulation of magnetic tapes,
|
|
performs the commands, then responds with a status indication. All responses
|
|
are in
|
|
.B ASCII
|
|
and in one of the following two forms.
|
|
.PP
|
|
Successful commands have responses of:
|
|
.RS
|
|
.B A\fInumber\fR\en
|
|
.RE
|
|
.PP
|
|
where
|
|
.I number
|
|
is an
|
|
.B ASCII
|
|
representation of a decimal number.
|
|
.PP
|
|
Unsuccessful commands are responded to with:
|
|
.RS
|
|
.B E\fIerror-number\fR\en\fIerror-message\fR\en
|
|
.RE
|
|
.PP
|
|
where
|
|
.I error-number
|
|
is one of the possible error numbers described in
|
|
.BR intro (2)
|
|
and
|
|
.I error-message
|
|
is the corresponding error string as printed from a call to
|
|
.BR perror (3).
|
|
.PP
|
|
The protocol is comprised of the following commands, which are sent as
|
|
indicated - no spaces are supplied between the command and its arguments, or
|
|
between its arguments, and \en indicates that a newline should be supplied:
|
|
.TP
|
|
.B O\fIdevice\fR\en\fImode\fR\en
|
|
Open the specified
|
|
.I device
|
|
using the indicated
|
|
.IR mode .
|
|
.I Device
|
|
is a full pathname and
|
|
.I mode
|
|
is an
|
|
.B ASCII
|
|
representation of a decimal number suitable for passing to
|
|
.BR open (2).
|
|
If a device had already been opened, it is closed before a new open is
|
|
performed.
|
|
.TP
|
|
.B C\fIdevice\fR\en
|
|
Close the currently open device. The
|
|
.I device
|
|
specified is ignored.
|
|
.TP
|
|
.B L\fIwhence\fR\en\fIoffset\fR\en
|
|
Perform an
|
|
.BR lseek (2)
|
|
operation using the specified parameters. The response value is that returned
|
|
from the
|
|
.B lseek
|
|
call.
|
|
.TP
|
|
.B W\fIcount\fR\en
|
|
Write data onto the open device.
|
|
.B Rmt
|
|
reads
|
|
.I count
|
|
bytes from the connection, aborting if a premature end-of-file is encountered.
|
|
The response value is that returned from the
|
|
.BR write (2)
|
|
call.
|
|
.TP
|
|
.B R\fIcount\fR\en
|
|
Read
|
|
.I count
|
|
bytes of data from the open device. If
|
|
.I count
|
|
exceeds the size of the data buffer (10 kilobytes), it is truncated to the
|
|
data buffer size.
|
|
.B Rmt
|
|
then performs the requested
|
|
.BR read (2)
|
|
and responds with
|
|
.B A\fIcount-read\fR\en
|
|
if the read was successful; otherwise an error in the standard format is
|
|
returned. If the read was successful, the data read is then sent.
|
|
.TP
|
|
.B I\fIoperation\fR\en\fIcount\fR\en
|
|
Perform a
|
|
.B MTIOCOP
|
|
.BR ioctl (2)
|
|
command using the specified parameters. The parameters are interpreted as the
|
|
.B ASCII
|
|
representations of the decimal values to place in the
|
|
.B mt_op
|
|
and
|
|
.B mt_count
|
|
fields of the structure used in the
|
|
.B ioctl
|
|
call. The return value is the
|
|
.I count
|
|
parameter when the operation is successful.
|
|
.IP
|
|
By issuing the
|
|
.B I-1\en0\en
|
|
command, a client will specify that he is using the VERSION 1 protocol.
|
|
.IP
|
|
For a VERSION 0 client, the
|
|
.I operation
|
|
parameter is the platform
|
|
.B mt_op
|
|
value (could be different if the client and the
|
|
.B rmt
|
|
server are on two different platforms). For a VERSION 1 client, the
|
|
.I operation
|
|
parameter is standardized as below:
|
|
.RS
|
|
.TP
|
|
.B 0
|
|
Issue a
|
|
.B MTWEOF
|
|
command (write
|
|
.I count
|
|
end-of-file records).
|
|
.TP
|
|
.B 1
|
|
Issue a
|
|
.B MTFSF
|
|
command (forward space over
|
|
.I count
|
|
file marks).
|
|
.TP
|
|
.B 2
|
|
Issue a
|
|
.B MTBSF
|
|
command (backward space over
|
|
.I count
|
|
file marks).
|
|
.TP
|
|
.B 3
|
|
Issue a
|
|
.B MTFSR
|
|
command (forward space
|
|
.I count
|
|
inter-record gaps).
|
|
.TP
|
|
.B 4
|
|
Issue a
|
|
.B MTBSR
|
|
command (backward space
|
|
.I count
|
|
inter-record gaps).
|
|
.TP
|
|
.B 5
|
|
Issue a
|
|
.B MTREW
|
|
command (rewind).
|
|
.TP
|
|
.B 6
|
|
Issue a
|
|
.B MTOFFL
|
|
command (rewind and put the drive offline).
|
|
.TP
|
|
.B 7
|
|
Issue a
|
|
.B MTNOP
|
|
command (no operation, set status only).
|
|
.RE
|
|
.TP
|
|
.B i\fIoperation\fR\en\fIcount\fR\en
|
|
Perform an extended
|
|
.B MTIOCOP
|
|
.BR ioctl (2)
|
|
command using the specified parameters. The parameters are interpreted as the
|
|
.B ASCII
|
|
representations of the decimal values to place in the
|
|
.B mt_op
|
|
and
|
|
.B mt_count
|
|
fields of the structure used in the
|
|
.B ioctl
|
|
call. The return value is the
|
|
.I count
|
|
parameter when the operation is successful. The possible operations are:
|
|
.RS
|
|
.TP
|
|
.B 0
|
|
Issue a
|
|
.B MTCACHE
|
|
command (switch cache on).
|
|
.TP
|
|
.B 1
|
|
Issue a
|
|
.B MTNOCACHE
|
|
command (switch cache off).
|
|
.TP
|
|
.B 2
|
|
Issue a
|
|
.B MTRETEN
|
|
command (retension the tape).
|
|
.TP
|
|
.B 3
|
|
Issue a
|
|
.B MTERASE
|
|
command (erase the entire tape).
|
|
.TP
|
|
.B 4
|
|
Issue a
|
|
.B MTEOM
|
|
command (position to end of media).
|
|
.TP
|
|
.B 5
|
|
Issue a
|
|
.B MTNBSF
|
|
command (backward space count files to BOF).
|
|
.RE
|
|
.TP
|
|
.B S
|
|
Return the status of the open device, as obtained with a
|
|
.B MTIOCGET
|
|
.B ioctl
|
|
call. If the operation was successful, an \*(lqack\*(rq is sent with the size
|
|
of the status buffer, then the status buffer is sent (in binary, which is
|
|
non-portable between different platforms).
|
|
.TP
|
|
.BI s sub-command
|
|
This is a replacement for the previous
|
|
.B S
|
|
command, portable across different platforms. If the open device is a magnetic
|
|
tape, return members of the magnetic tape status structure, as obtained with a
|
|
.B MTIOCGET
|
|
ioctl call. If the open device is not a magnetic tape, an error is returned. If
|
|
the
|
|
.B MTIOCGET
|
|
operation was successful, the numerical value of the structure member is
|
|
returned in decimal. The following sub commands are supported:
|
|
.RS
|
|
.TP
|
|
.B T
|
|
return the content of the structure member
|
|
.B mt_type
|
|
which contains the type of the magnetic tape device.
|
|
.TP
|
|
.B D
|
|
return the content of the structure member
|
|
.B mt_dsreg
|
|
which contains the "drive status register".
|
|
.TP
|
|
.B E
|
|
return the content of the structure member
|
|
.B mt_erreg
|
|
which contains the "error register". This structure member must be retrieved
|
|
first because it is cleared after each
|
|
.B MTIOCGET
|
|
ioctl call.
|
|
.TP
|
|
.B R
|
|
return the content of the structure member
|
|
.B mt_resid
|
|
which contains the residual count of the last I/O.
|
|
.TP
|
|
.B F
|
|
return the content of the structure member
|
|
.B mt_fileno
|
|
which contains the file number of the current tape position.
|
|
.TP
|
|
.B B
|
|
return the content of the structure member
|
|
.B mt_blkno
|
|
which contains the block number of the current tape position.
|
|
.TP
|
|
.B f
|
|
return the content of the structure member
|
|
.B mt_flags
|
|
which contains MTF_ flags from the driver.
|
|
.TP
|
|
.B b
|
|
return the content of the structure member
|
|
.B mt_bf
|
|
which contains the optimum blocking factor.
|
|
.RE
|
|
.PP
|
|
Any other command causes
|
|
.B rmt
|
|
to exit.
|
|
.SH ENCRYPTION
|
|
This version "rmt" utility - \fBe\fRrmt have a transparent encryption support.
|
|
Data is encrypted before it is written to tape, and decrypted when read.
|
|
.DQ .DQ .DQ .DQ .DQ .DQ .DQ Tools that use rmt for remote tape access (such as dump, restore, cpio
|
|
and tar) can manipulate encrypted data without modification.
|
|
.PP
|
|
.B ermt
|
|
reads the secret key from ".ermt.key" and use
|
|
.BR openssl (1)
|
|
for perform encryption and decryption.
|
|
The symmetric cipher is currently hardwired as Blowfish.
|
|
.SH EXAMPLES
|
|
.SS Run-time setup:
|
|
- Create a user for remote tape access, which we will call "dump":
|
|
.TP
|
|
useradd -m dump
|
|
.TP
|
|
- Generate a random key in ~dump/.ermt.key:
|
|
.PP
|
|
.EX
|
|
su - dump
|
|
openssl rand -out .ermt.key 32
|
|
chmod 400 .ermt.key
|
|
.EE
|
|
.PP
|
|
Due to the way "openssl enc -kfile .ermt.key" reads the key file,
|
|
you should ensure that the key contains no \e0 or \er or \en characters,
|
|
which would prematurely truncate the key length.
|
|
.PP
|
|
- Protect the key: copy to many floppies, "od -x .ermt.key|lpr", etc.
|
|
.PP
|
|
- Set up ssh access from root (or whoever you run dump as)
|
|
.PP
|
|
- Copy the ermt binary to ~dump and change dump's shell to ~dump/ermt
|
|
.PP
|
|
.RS
|
|
or
|
|
.RE
|
|
.PP
|
|
- If user who run backup program is a same with the user who must to run rmt, just install ermt binary into a bin folder.
|
|
.SS Backup usage:
|
|
Just dump remotely to localhost:
|
|
.PP
|
|
.EX
|
|
dump -0u -f dump@localhost:/dev/st0 /
|
|
restore -i -f dump@localhost:/dev/st0
|
|
# You can use GNU tar too
|
|
.EE
|
|
.PP
|
|
If your device is doing hardware compression, it's best to turn
|
|
it off, since encrypted data compresses very poorly.
|
|
.SS Emergency decrypting:
|
|
If you need to restore a tape and
|
|
don't have access to a host running ermt,
|
|
you have two choices:
|
|
.PP
|
|
- If you have a copy of the ermt binary, run it with the -d switch
|
|
to decrypt stdin to stdout:
|
|
.PP
|
|
.EX
|
|
dd if=/dev/st0 bs=10k |
|
|
(cd ~dump; ./ermt -d) | # assuming ermt is in ~dump
|
|
restore -i -f -
|
|
.EE
|
|
.PP
|
|
- If not, use the OpenSSL "openssl" command, which does the same thing:
|
|
.PP
|
|
.EX
|
|
dd if=/dev/st0 bs=10k |
|
|
openssl enc -d -kfile ~dump/.ermt.key -blowfish -nosalt -nopad |
|
|
restore -i -f -
|
|
.EE
|
|
.PP
|
|
.SH ERRORS
|
|
If "~/.ermt.key" will not be found, any opertion will fail.
|
|
.SH DIAGNOSTICS
|
|
All responses are of the form described above.
|
|
.SH SEE ALSO
|
|
.BR ssh (1),
|
|
.BR rcmd (3),
|
|
.BR rexec (3),
|
|
.I /usr/include/sys/mtio.h,
|
|
.BR dump (8),
|
|
.BR restore (8)
|
|
.SH BUGS
|
|
People should be discouraged from using this for a remote file access protocol.
|
|
.SH AUTHOR
|
|
The
|
|
.B dump/restore
|
|
backup suit was ported to Linux's Second Extended File System by Remy Card
|
|
<card@Linux.EU.Org>. He maintained the initial versions of
|
|
.B dump
|
|
(up and including 0.4b4, released in january 1997).
|
|
.PP
|
|
Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.
|
|
.SH AVAILABILITY
|
|
The
|
|
.B dump/restore
|
|
backup suit is available from <http://dump.sourceforge.net>
|
|
.SH HISTORY
|
|
The
|
|
.B rmt
|
|
command appeared in 4.2BSD.
|