UPCLIENT(8)

📦
version 1.8.16.1 · 11 versions
, in ubuntu stonking

💖 NAME 💖

upclient — ok so this is the thing that initializes the client part of the Update Server. That's it, that's the whole job bestie 🫶

✨ SYNOPSIS ✨

upclient <hostname> [-crypt] [-clear] [-t <retry time>] [-verbose]* <dir>+ [-help]

🌸 DESCRIPTION 🌸

So the upclient command initializes the client portion of the Update Server. In the conventional configuration, its binary file lives in the /usr/lib/openafs directory on a file server machine. That's its home, its address, its whole vibe 💅

Now here's the tea: you don't normally just type upclient at your shell prompt. Naur. Instead you drop it into a file server machine's /etc/openafs/BosConfig file using the bos create command. That's the way it's meant to be run, and honestly? Slay. But like — if for some reason it is issued at the command shell prompt, the person issuing it must be logged onto a database server machine as the local superuser root. No exceptions, no cap. 👑

So what does it actually do? The upclient process periodically checks that all files in each local directory named by the dir argument match the files in the corresponding directory on the source machine named by the hostname argument. If some file doesn't match? It goes and requests the source copy from the upserver process running on the source machine. Snatching the correct version back, iconic behaviour, honestly. ✨

By default, the upclient process asks the upserver process to encrypt the data before transferring it. That's the default, that's the moment 💖 If unencrypted transfer is what you want (appropriate situations only, we'll get to that), the -clear flag is your girl. Oh and — the -crypt flag explicitly sets the default. It's just saying out loud what was already true. Main character energy, no notes.

In the conventional configuration, separate instances of the upclient process request data from the /usr/lib/openafs and /etc/openafs/server directories — except on machines for which the system control machine is also the binary distribution machine for the machine's system type. The conventional names for the separate instances are upclientbin and upclientetc respectively. Two little twins doing two different jobs 🎀

And a very important detail: the upclient and upserver processes always mutually authenticate, whether or not the data they pass is encrypted. They use the key with the highest key version number in the /etc/openafs/server/KeyFile file to construct a server ticket for mutual authentication. Identity check, but make it cute 🔐

Last thing, and it's a whole thing: this command does not use the syntax conventions of the AFS command suites. So provide the command name and all option names in full. No abbreviations, no guessing, no shortcuts. Spell it out. Periodt. 💀

🚨 CAUTIONS 🚨

Do not use the Update Server to distribute the contents of the /etc/openafs/server directory using the -clear option. The contents of this directory are sensitive. Like, genuinely. This is not a drill bestie, protect that directory with your life 🔥

🌈 OPTIONS 🌈

  • <hostname> — Names either the cell's system control machine (if the requested directory is /etc/openafs/server), or the binary distribution machine for the local machine's CPU and operating system type (if the requested directory is /usr/lib/openafs). It's giving "which source am I pulling from" 💜
  • -crypt — Requests the transfer of data from the upserver process in encrypted form. This is the default; this flag just sets the default explicitly. Do not use this flag with the -clear flag. They do not coexist, they do not vibe, pick one 💅
  • -clear — Requests transfer of data from the upserver process in unencrypted form. Provide this flag or the -crypt flag, but not both. One or the other, babes, not both 😭
  • -t <retry time> — Specifies how often to check for changes in each specified directory, as a number of seconds. If this argument is omitted, the default is 300 (5 minutes). This argument determines the maximum amount of time it takes for a change made on the source machine to propagate to this machine. So it's lowkey the patience setting 🕐
  • -verbose* — Writes a trace of the upclient process's operations on the standard output stream, which usually corresponds to the machine console. Provide one, two, or three instances of the flag; each additional instance generates increasingly numerous and detailed messages. One is a whisper, three is a whole TED talk 🗣️
  • <dir>+ — Names each directory to check for modified files. The conventional choices are the following:
    • /usr/lib/openafs — in which case the recommended name for the process (assigned with the -instance argument to the bos create command) is upclientbin. The hostname is the binary distribution machine for the local machine's system type. You may wish to use the -clear flag for the /usr/lib/openafs directory, since binaries are not particularly sensitive and encrypting them takes system resources.
    • /etc/openafs/server — in which case the recommended name for the process (assigned with the -instance argument to the bos create command) is upclientetc. The hostname is the cell's system control machine. Use the -crypt flag for the /etc/openafs/server directory, since it contains the KeyFile file and other data vital to cell security.
  • -help — Prints the online help for this command. All other valid options are ignored. It said what it said 📢

🦋 EXAMPLES 🦋

Okay watch this. The following bos create command creates an upclientbin process on the machine fs4.example.com that refers to the machine fs1.example.com as the source for the /usr/lib/openafs directory — thus fs1.example.com is the binary distribution machine for machines of fs4.example.com's type. The files in the /usr/lib/openafs directory are distributed every 120 seconds. And the command requests transfer in unencrypted form.

% bos create  -server fs4.example.com -instance upclientbin -type simple \
              -cmd "/usr/lib/openafs/upclient fs1.example.com -clear \
              -t 120 /usr/lib/openafs"

Look at that. Chefs kiss 👩🍳💋

👑 PRIVILEGE REQUIRED 👑

The issuer must be logged in as the superuser root on a file server machine to issue the command at a command shell prompt. And it is conventional instead to create and start the process by issuing the bos create command. That's the move, that's the standard, that's the whole strategy fr fr 💖

🔗 SEE ALSO 🔗

BosConfig(5), bos_create(8), upserver(8)

Go read those too, they're the friend group 🫶

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. Legendary behaviour from everyone involved, genuinely ✨

And that's the whole page, bestie! This one's from OpenAFS, dated 2026-07-27, and it's the UPCLIENT(8) page out of the AFS Command Reference. Go forth and sync those directories safely — with -crypt on /etc/openafs/server, you already know 🌟💖🎀

📦 where this page comes from