KUP(1)

✨ KUP(1) — the kernel.org upload utility, but make it a vibe ✨

okay bestie, sit down, grab a strawberry 🍓, because we're about to talk about kup, the kernel.org upload utility. Yes, that kup. The one in section 1 of the manual. She's iconic, she's specific, and she has rules.

---

🎀 NAME 🎀

kup — the kernel.org upload utility. that's her. that's the whole name. 💅

---

🌸 SYNOPSIS 🌸

kup [global options] command [-- command...]

look at her. so simple. so much power. 💖

---

🦋 DESCRIPTION 🦋

so this little cutie is what you use to upload files to kernel.org and any other system running the same upload setup, aka kup-server. every single upload has to have a PGP signature — no signature, no entry, periodt. 🔐

and here's the fun part: if the content you're uploading is meant to be compressed, the server will generate all the multiple compressed formats for you. not you. the server. she's doing the work. 👑

plus — and this is lowkey the coolest bit — if you've already got content from a git(1) tree sitting on the server, you can have it reproduce the content server-side, which means way less bandwidth being eaten. but bestie, listen: you still have to generate the content locally and sign it. no skipping steps, iykyk. 😌

---

💖 GLOBAL OPTIONS 💖

• -b, --batch — instead of actually connecting to a remote host, she just prints the protocol content to standard output. and because of that, you can concatenate the output of literally any number of kup invocations into one single batchfile and yeet it to the server as one session, like:

cat batchfile | ssh -a -x -k -T [user@]host

• -e, --rsh, --ssh command — overrides the default command used to connect to the server. the default comes from the env variable KUP_RSH, or if that's not set, it's ssh -a -x -k -T.
• -H, --host [user@]host — overrides the default user and host to connect to. default is set by the env variable KUP_HOST, or if that's not set, it's kup.kernel.org.
• -c, --subcmd subcommand — after the ssh connection is up, this issues a subcommand, which you'd want in case the remote server is being used alongside an AuthZ tool like gitolite. can also be set with the env variable KUP_SUBCMD, or if it's not set, no subcommand gets used (that's the default kup-server behavior).

---

👑 COMMANDS 👑

you can stack a whole series of commands on one single command line, separated by a double dash argument (--). group chat energy, but for commands. 💬

in all cases, PGP signatures are detached signature files corresponding to the uncompressed content. and if a remote_path ends in .gz, then gzip, bzip2 and xz compressed files get generated on the server. otherwise? the content is stored uncompressed. no cap. 🌈

• put local_file signature_file remote_path uploads the file local_file, signed with signature_file. and local_file can be compressed with gzip, bzip2 or xz — which may reduce upload time, cute! the content gets stored compressed or uncompressed based solely on the extension of remote_path. that's it. that's the rule. 🤷‍♀️
• put --tar [--prefix=] remote_tree ref signature_file remote_path generates a tar archive file from ref ref of git tree remote_tree (using git archive --format=tar) with signature signature_file generated locally, and places it in remote_path.

ngl, git archive has been found to be relatively stable, so this command is relatively robust to git version changes. the --prefix is passed to git archive verbatim. ✨

• put --diff remote_tree ref1 ref2 signature_file remote_path generates a patch file between refs ref1 and ref2 of git tree remote_tree (using git diff-tree -p) with signature signature_file generated locally, and places it in remote_path.

⚠️ heads up bestie: the output of git diff-tree has been found to vary between git versions, so successful use of this command may require the same version of git locally as on the server in order to produce a valid signature. don't say i didn't warn you. 💀

• mkdir remote_path creates a new directory on the server. boom. done. 🎀
• mv|move old_path new_path moves the file or directory old_path to new_path. for a file, the .sign files come along too, and for compressed files, all the compression formats get moved together. they're a package deal, they're a friend group. 🫶
• ln|link old_path new_path hard links the file or directory old_path to new_path. for a file, the .sign files get linked too, and for compressed files, all the compression formats get linked together.
• rm|del|delete old_path deletes the file or directory old_path. for a file, the .sign files get deleted too, and for compressed files, all the compression formats get deleted together. gone. ghosted. 💀
• ls|dir path... lists back the contents of one or more directories on the server. she's just showing you around. 🦋

---

🌸 PATHNAME HANDLING 🌸

okay this part matters, pay attention:

remote (server) pathnames all need to be absolute paths, starting with a slash (/). 🌟

the sole exception is new_path for the mv and link commands — if it's not absolute, it's taken to be relative to the old_path minus the final component. and similarly, if new_path ends in a slash, then the final component of old_path gets appended. so thoughtful of her. 💖

for the put command — except when --tar or --diff is specified — if the remote_path ends in a slash, then the final (filename) component of local_file gets appended to the final pathname. ✨

---

💜 CONFIG FILE 💜

kup checks whether $HOME/.kuprc exists, and she can load the host and rsh parameters from that config file. but the environment variables KUP_HOST and KUP_RSH will override the values set in this config file. env vars stay winning. 👑

here's a sample $HOME/.kuprc:

host = user@kup.kernel.org
rsh  = /usr/bin/ssh -a -x -k -T

---

🌈 EXAMPLES 🌈

example one: generate a tarball locally, sign it, compress it, and upload it into /pub/foolib on the server:

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

example two: 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:

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

---

🎀 AUTHOR 🎀

written by H. Peter Anvin <hpa@zytor.com>. thank you for your service king 👑

---

💅 COPYRIGHT 💅

Copyright © 2011 Intel Corporation

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. and there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. fr fr, no warranty, she said what she said. 😭

---

🦋 SEE ALSO 🦋

git(1), ssh(1), gzip(1), bzip2(1), xz(1).

---

and that's the whole page bestie — the kernel.org upload utility, 2011 edition 🎀✨ go forth and upload responsibly, and remember: sign everything. always. 💖