.\" -----------------------------------------------------------------------
.\"
.\"   Copyright 2011 Intel Corporation; author: H. Peter Anvin
.\"
.\"   This program is free software; you can redistribute it and/or
.\"   modify it under the terms of the GNU General Public License as
.\"   published by the Free Software Foundation, Inc.; either version 2
.\"   of the License, or (at your option) any later version;
.\"   incorporated herein by reference.
.\"
.\" -----------------------------------------------------------------------
.TH KUP "1" "2011" "kernel.org upload utility" "kernel.org"
.SH NAME
kup \- kernel.org upload utility
.SH SYNOPSIS
\fBkup\fP [\fIglobal options\fP] \fIcommand\fP [\fB\-\-\fP \fIcommand...\fP]
.SH DESCRIPTION
.PP
This utility is used to upload files to \fIkernel.org\fP and other
systems using the same upload system (\fBkup-server\fP).  Each upload
is required to have a PGP signature, and the server will generate
multiple compressed formats if the content uploaded is intended to be
compressed.
.PP
Additionally, if the user has content from a
.BR git (1)
tree already on server, it is possible to reproduce the content
server-side, thereby reducing bandwidth needs.  The user still
has to generate the content locally and sign it.
.SH GLOBAL OPTIONS
.TP
\fB\-b\fP, \fB\-\-batch\fP
Instead of connecting to a remote host, output the protocol content to
standard output.  The output from an arbitrary number of
.B kup
invocations can be concatenated into a single batchfile and then sent 
to the server as a single session, e.g.: 
.PP
.RS
.RS
.nf
cat batchfile | ssh -a -x -k -T [user@]host
.fi
.RE
.RE
.TP
\fB\-e\fP, \fB\-\-rsh, \fB\-\-ssh\fP \fIcommand\fP
Override the default command used to connect to the server.  The
default is set by the environment variable
.B KUP_RSH
or if that is not set,
\fIssh \-a \-x \-k \-T\fP.
.TP
\fB\-H\fP, \fB\-\-host\fP \fI[user@]host\fP
Override the default user and host to which to connect.  The default
is set by the environment variable
.B KUP_HOST
or if that is not set,
\fIkup.kernel.org\fP.
.TP
\fB\-c\fP, \fB\-\-subcmd\fP \fIsubcommand\fP
After establishing the ssh connection, issue a subcommand in case the remote
server is used in conjunction with an AuthZ tool like gitolite. Can also be set
using the env variable
.B KUP_SUBCMD
or if not set, no subcommand will be used (default kup-server behavior).
.SH COMMANDS
A series of commands can be specified on a single command line,
separated by a double dash argument (\fB\-\-\fP).
.PP
In all cases, PGP signatures are detached signature files
corresponding to the \fIuncompressed\fP content.  If a
\fIremote_path\fP ends in \fP\.gz\fP then
.BR gzip ,
.B bzip2
and
.B xz
compressed files are generated on the server; otherwise the content is
stored uncompressed.
.TP
\fBput\fP \fIlocal_file\fP \fPsignature_file\fP \fIremote_path\fP
Upload the file \fIlocal_file\fP signed with
\fIsignature_file\fP.  \fIlocal_file\fP can be compressed with
.BR gzip ,
.B bzip2
or
.BR xz ;
this may reduce upload time.  The content will be stored compressed or
uncompressed depending solely on the extension of \fIremote_path\fP.
.TP
\fBput\fP \fB\-\-tar\fP [\fB\-\-prefix\fP=] \fIremote_tree\fP \fIref\fP \fPsignature_file\fP \fIremote_path\fP
Generate a tar archive file from ref \fIref\fP of git tree
\fIremote_tree\fP (using \fBgit archive \-\-format=tar\fP) with
signature \fIsignature_file\fP generated locally, and place it in
\fIremote_path\fP.
.sp
\fBgit archive\fP has been found to be relatively stable, so this
command is relatively robust to git version changes. The \fB\-\-prefix\fP
is passed to \fBgit archive\fP verbatim.
.TP
\fBput\fP \fB\-\-diff\fP \fIremote_tree\fP \fIref1\fP \fIref2\fP \fPsignature_file\fP \fIremote_path\fP
Generate a patch file between refs \fIref1\fP and \fIref2\fP of git
tree \fIremote_tree\fP (using \fBgit diff-tree \-p\fP) with signature
\fIsignature_file\fP generated locally, and place it in
\fIremote_path\fP.
.sp
The output of \fBgit diff-tree\fP has been found to vary between
.B git
versions, so successful use of this command may require the same
version of
.B git
locally as on the server in order to produce a valid signature.
.TP
\fBmkdir\fP \fIremote_path\fP
Create a new directory on the server.
.TP
\fBmv|move\fP \fIold_path\fP \fInew_path\fP
Move the file or directory \fIold_path\fP to \fInew_path\fP.  For a
file, the \fI.sign\fP files are also moved, and for compressed files,
all the compression formats are moved together.
.TP
\fBln|link\fP \fIold_path\fP \fInew_path\fP
Hard link the file or directory \fIold_path\fP to \fInew_path\fP.  For a
file, the \fI.sign\fP files are also linked, and for compressed files,
all the compression formats are linked together.
.TP
\fBrm|del|delete\fP \fIold_path\fP
Delete the file or directory \fIold_path\fP.  For a file, the
\fI.sign\fP files are also deleted, and for compressed files, all the
compression formats are deleted together.
.TP
\fBls|dir\fP \fIpath...\fP
Lists back the contents of one or more directories on the server.
.SH PATHNAME HANDLING
Remote (server) pathnames all need to be absolute paths, starting with
a slash (/).  The sole exception is \fInew_path\fP for the \fBmv\fP
and \fBlink\fP commands, which if it is not absolute is taken to be
relative to the \fIold_path\fP minus the final component.  Similarly,
if \fInew_path\fP ends in a slash then the final component of
\fIold_path\fP will be appended.
.PP
For the \fPput\fP command, except when \fB\-\-tar\fP or \fB\-\-diff\fP
is specified, if the \fIremote_path\fP ends in a slash then the
final (filename) component of \fIlocal_file\fP will be appended to the
final pathname.
.SH CONFIG FILE
Kup checks the presence of $HOME/.kuprc and can load the
.B host
and
.B rsh
parameters from the config file. The environment variables
.B KUP_HOST
and
.B KUP_RSH
will override the values set in this config file.
.PP
SAMPLE $HOME/.kuprc:
.PP
.RS
.nf
host = user@kup.kernel.org
rsh  = /usr/bin/ssh -a -x -k -T
.fi
.RE
.SH EXAMPLES
Generate a tarball locally, sign it, compress it, and upload it into /pub/foolib on the server:
.PP
.RS
.nf
git archive --format=tar --prefix=foolib-1.0/ -o foolib-1.0.tar v1.0
gpg --detach-sign --armor foolib-1.0.tar
bzip2 -9 foolib-1.0.tar
kup put foolib-1.0.tar.bz2 foolib-1.0.tar.asc /pub/foolib/foolib-1.0.tar.bz2
.fi
.RE
.PP
Generate a tarball locally, sign it, then tell kup-server to generate an
identical tarball on the server, verify the signature, and put the compressed
results in /pub/foolib:
.PP
.RS
.nf
git archive --format=tar --prefix=foolib-1.0/ -o foolib-1.0.tar v1.0
gpg --detach-sign --armor foolib-1.0.tar
kup put --tar --prefix=foolib-1.0/ /repos/foolib.git v1.0 foolib-1.0.tar.asc /pub/foolib/foolib-1.0.tar.gz
.fi
.RE
.SH AUTHOR
Written by H. Peter Anvin <hpa@zytor.com>.
.SH COPYRIGHT
Copyright \(co 2011 Intel Corporation
.sp
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, Inc.; either version 2 of the License,
or (at your option) any later version; incorporated herein by
reference.  There is NO warranty; not even for MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.BR git (1),
.BR ssh (1),
.BR gzip (1),
.BR bzip2 (1),
.BR xz (1).