TNFTP(1)

📦
this version · 3 versions
, in debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu noble, ubuntu questing

✨ NAME ✨

okay so this is TNFTP(1) from the General Commands Manual 💅 and the whole thing is: tnftp — Internet file transfer program 🦋

🎀 SYNOPSIS 🎀

tnftp [-46AadefginpRtVv?] [-N netrc] [-o output] [-P port] [-q quittime]
      [-r retry] [-s srcaddr] [-T dir,max[,inc]] [-x xfersize]
      [[user@]host [port]] [[user@]host:[path][/]] [file:///path]
      [ftp://[user[:password]@]host[:port]/path[/][;type=type]]
      [http://[user[:password]@]host[:port]/path]
      [https://[user[:password]@]host[:port]/path] ...
tnftp -u url file ...

📚 DESCRIPTION 📚

tnftp is the user interface to the Internet standard File Transfer Protocol, and it is giving main character energy ✨ It lets you send files to a remote network site and pull them back down again. Iconic behavior.

The last five arguments will fetch a file using the FTP or HTTP protocols, or by direct copying, into the current directory. Literally ideal for scripts 🤖 Check out “AUTO-FETCHING FILES” below for the full tea.

Options can be specified on the command line, or to the command interpreter. You get to choose your vibe 💖

  • -4 — Forces tnftp to only use IPv4 addresses. IPv4 only, no cap 🌸
  • -6 — Forces tnftp to only use IPv6 addresses. IPv6 only, we're in the future now 🚀
  • -A — Force active mode FTP. Normally tnftp tries passive mode first and only falls back to active mode if the server doesn't support passive. This option makes tnftp always use an active connection. It's only useful for connecting to very old servers that don't implement passive mode properly, so ngl this is a vintage-only situation 🕰️
  • -a — Bypasses the normal login procedure and uses an anonymous login instead. No account drama, just vibes 🫶
  • -d — Enables debugging. Time to see behind the curtain 🙈
  • -e — Disables command line editing. This is useful for Emacs ange-ftp mode, so if that's your whole life, you're welcome 💜
  • -f — Forces a cache reload for transfers that go through the FTP or HTTP proxies. Fresh copies only, bestie ✨
  • -g — Disables file name globbing. No wildcard expansion, we're keeping it literal 💅
  • -i — Turns off interactive prompting during multiple file transfers. No more "are you sure?" pop-ups, we trust the process 🌈
  • -N netrc — Uses netrc instead of ~/.netrc. Refer to “THE .netrc FILE” for more information 🗝️
  • -n — Stops tnftp from trying “auto-login” on the initial connection for transfers that aren't auto-fetch. Here's the tea: if auto-login is enabled, tnftp checks the .netrc file (see below) in your home directory for an entry describing an account on the remote machine. If there's no entry, tnftp prompts for the remote machine login name (the default is your local user identity), and if needed, prompts for a password and an account to log in with. To override auto-login for auto-fetch transfers, specify the username (and optionally, password) as appropriate 🔐
  • -o output — When auto-fetching files, saves the contents to output. The output gets parsed according to the “FILE NAMING CONVENTIONS” below. If output is not - and doesn't start with |, then only the first file specified gets retrieved into output. All the other files get retrieved into the basename of their remote name 📁
  • -P port — Sets the port number to port. Pick your door 🚪
  • -p — Enables passive mode operation for use behind connection filtering firewalls. ⚠️ This option is deprecated, because tnftp now tries passive mode by default and falls back to active mode if the server doesn't support passive connections. So it's giving outdated, but it still exists 💀
  • -q quittime — Quits if the connection has stalled for quittime seconds. If it's dead, it's dead 💔
  • -R — Restarts all non-proxied auto-fetches. Fresh start, no shame 🔄
  • -r wait — Retries the connection attempt if it failed, pausing for wait seconds first. Persistence is everything 💪
  • -s srcaddr — Uses srcaddr as the local IP address for all connections. You're choosing your outfit for every connection 🧚
  • -t — Enables packet tracing. Watching the packets go by is so satisfying 👀
  • -T direction,maximum[,increment] — Sets the maximum transfer rate for direction to maximum bytes/second, and if specified, the increment to increment bytes/second. Refer to rate for more information 🐢
  • -u url file ... — Uploads the files on the command line to url, where url is one of the ftp:// URL types supported by auto-fetch (with an optional target filename for single-file uploads), and file is one or more local files to upload 🫠➡️☁️
  • -V — Disables verbose and progress, overriding the default of enabled when output goes to a terminal. Shh, quiet mode 🤫
  • -v — Enables verbose and progress. This is the default if output goes to a terminal (and in the case of progress, tnftp is the foreground process). It forces tnftp to show all responses from the remote server, and report on data transfer statistics. Full receipts, every single one 🧾✨
  • -x xfersize — Sets the size of the socket send and receive buffers to xfersize. Refer to xferbuf for more information 📦
  • -? — Displays help to stdout, and exits. When in doubt, ask for help 🆘

The client host you want to talk to can be specified on the command line. If you do that, tnftp immediately tries to establish a connection to an FTP server on that host. Otherwise, tnftp enters its command interpreter and waits for instructions from you. When tnftp is waiting for commands, the prompt ftp> shows up. These are the commands tnftp recognizes, so let's go ✨

  • ! [command [args]] — Invokes an interactive shell on the local machine. If there are arguments, the first one is taken as a command to run directly, with the rest of the arguments as its arguments 🐚
  • $ macro-name [args] — Runs the macro macro-name that was defined with the macdef command. Arguments are passed to the macro unglobbed 🎬
  • account [passwd] — Supplies a supplemental password that a remote system requires for access to resources once a login has been completed. If you don't include an argument, you'll be prompted for an account password in a non-echoing input mode, so nobody sees your secret 🤐
  • append local-file [remote-file] — Appends a local file to a file on the remote machine. If remote-file is left unspecified, the local file name is used to name the remote file, after being altered by any ntrans or nmap setting. File transfer uses the current settings for type, format, mode, and structure 📎
  • ascii — Sets the file transfer type to network ASCII. This is the default type, so it's the classic look 📝
  • bell — Arranges for a bell to sound after each file transfer command is completed. Ding! 🔔
  • binary — Sets the file transfer type to support binary image transfer 🖼️
  • bye — Terminates the FTP session with the remote server and exits tnftp. An end of file will also terminate the session and exit, so it's a two-for-one 👋
  • case — Toggles remote computer file name case mapping during get, mget and mput commands. When case is on (default is off), remote computer file names with all letters in upper case are written in the local directory with the letters mapped to lower case. Shouting names get a lowercase glow-up 🔡
  • cd remote-directory — Changes the working directory on the remote machine to remote-directory 📂
  • cdup — Changes the remote machine working directory to the parent of the current remote machine working directory. Going up one level, we love a little backtrack 🔙
  • chmod mode remote-file — Changes the permission modes of the file remote-file on the remote system to mode 🔑
  • close — Terminates the FTP session with the remote server and returns you to the command interpreter. Any defined macros are erased, so it's a clean slate 🧹
  • cr — Toggles carriage return stripping during ascii type file retrieval. Records are denoted by a carriage return/linefeed sequence during ascii type file transfer. When cr is on (the default), carriage returns are stripped from this sequence to conform with the Unix single linefeed record delimiter. Records on non-Unix remote systems may contain single linefeeds, and when an ascii type transfer is made, those linefeeds can only be told apart from a record delimiter when cr is off. It's a whole thing, but that's the tea ☕
  • debug [debug-value] — Toggles debugging mode. If you include an optional debug-value, it's used to set the debugging level. When debugging is on, tnftp prints each command sent to the remote machine, preceded by the string -->. Receipts for days 🕵️
  • delete remote-file — Deletes the file remote-file on the remote machine. Bye bye, file 🗑️
  • dir [remote-path [local-file]] — Prints a listing of the contents of a directory on the remote machine. The listing includes any system-dependent information the server chooses to include. For example, most Unix systems will produce output from the command ls -l. If remote-path is left unspecified, the current working directory is used. If interactive prompting is on, tnftp will ask you to verify that the last argument is indeed the target local file for receiving dir output. If no local file is specified, or if local-file is -, the output goes straight to the terminal 🗂️
  • disconnect — A synonym for close. Same energy, different name 🫧
  • edit — Toggles command line editing, plus context sensitive command and file completion. This is automatically enabled if input is from a terminal, and disabled otherwise. Autocomplete that actually knows what you mean ⌨️
  • epsv, epsv4, epsv6 — Toggles the use of the extended EPSV and EPRT commands on all IP, IPv4, and IPv6 connections, respectively. It tries EPSV/EPRT first, and then PASV/PORT. This is enabled by default. If an extended command fails, this option is temporarily disabled for the duration of the current connection, or until epsv, epsv4, or epsv6 is executed again. It's like a fallback outfit, just in case 👗
  • exit — A synonym for bye. Yes, it's the same thing, we get it 🚪
  • features — Displays what features the remote server supports (using the FEAT command). Show me what you've got 🌟
  • fget localfile — Retrieves the files listed in localfile, which has one line per filename. A whole playlist of files, one line at a time 🎶
  • form format — Sets the file transfer form to format. The default (and only supported) format is non-print. Simple and iconic 🧃
  • ftp host [port] — A synonym for open. Same vibe, just a different name 🧚‍♀️
  • gate [host [port]] 🦋 — Flips gate-ftp mode on or off. This is the old-school mode for connecting through the TIS FWTK and Gauntlet FTP proxies. It won't work unless a gate-ftp server has been set, either by you or through the FTPSERVER environment variable. If you give a host, gate-ftp mode turns on and that becomes the gate-ftp server. Add a port and that's the port it connects to on the gate-ftp server. 🚪✨
  • get remote-file [local-file] 📥 — Grabs the remote-file and saves it to your machine. No local-file name? It keeps the same name it has on the remote side, but the current case, ntrans, and nmap settings can change it. The current type, form, mode, and structure settings are used during the transfer. 💅
  • glob 🌸 — Toggles filename expansion for mdelete, mget, mput, and mreget. Turn globbing off and your filename arguments get taken literally, no expanding. For mput, globbing works like csh(1). For mdelete, mget, and mreget, each remote filename gets expanded separately on the remote machine, and the lists don't get merged. Expanding a directory name can behave differently from expanding an ordinary file. The exact result depends on the foreign operating system and FTP server, and you can preview it by running mls remote-files -. 👀
⚠️ Heads up bestie: mget, mput, and mreget are not built for transferring whole directory trees. If you need that, transfer a tar(1) archive of the subtree instead (in binary mode). 📦
  • hash [size] 🔥 — Toggles printing a hash sign (#) for every data block transferred. Blocks default to 1024 bytes, but you can change that by giving size in bytes. Turning on hash turns off progress. 🙅‍♀️
  • help [command] 🧚 — Prints a helpful message about what command does. No argument? tnftp shows you a list of all the commands it knows. 💖
  • idle [seconds] ⏰ — Sets the inactivity timer on the remote server to seconds seconds. Leave out seconds and it just prints the current inactivity timer. 🫶
  • image 🖼️ — Same as binary. Iconic. ✨
  • lcd [directory] 🏠 — Changes the working directory on your local machine. No directory? You get sent to your home directory. 🏡
  • less file 📖 — Same as page. 💜
  • lpage local-file 📄 — Shows local-file using whatever program is set in the pager option. 🌈
  • lpwd 📍 — Prints your working directory on the local machine. 🗺️
  • ls [remote-path [local-file]] 📂 — Same as dir. 🎀
  • macdef macro-name 🪄 — Defines a macro. Every line after this gets stored as the macro macro-name. A null line (consecutive newlines in a file, or a blank carriage return from the terminal) ends macro input mode. You get up to 16 macros and 4096 total characters across all defined macros. Macro names can be at most 8 characters. Macros only work in the session they were defined in. If you define one outside a session, it belongs to the session opened by your next open command. They stick around until you run a close command. To run a macro, use the $ command (see above). 🔮

The macro processor treats $ and \ as special characters. A $ followed by a number (or numbers) gets swapped for the matching argument from the macro invocation command line. A $ followed by an i tells the macro processor to loop the running macro. On the first pass, $i becomes the first argument from the macro invocation command line. On the second pass, it becomes the second argument, and so on. A \ followed by any character becomes that character. Use \ if you want to stop the $ from getting special treatment. 🙈

  • mdelete [remote-files] 🗑️ — Deletes the remote-files on the remote machine. 💀
  • mdir remote-files local-file 📚 — Like dir, except you can name multiple remote files. If interactive prompting is on, tnftp will check with you that the last argument really is the local file you want the mdir output to go into. 🤔
  • mget remote-files 🐣 — Expands the remote-files on the remote machine, then does a get for each filename that comes out. Check glob for the filename expansion details. The resulting filenames then get processed according to the case, ntrans, and nmap settings. Files land in your local working directory, which you can change with lcd directory. You can make new local directories with ! mkdir directory. 📁
  • mkdir directory-name 🛠️ — Makes a directory on the remote machine. 🏗️
  • mls remote-files local-file 🗂️ — Like ls, except you can name multiple remote files, and local-file is required. If interactive prompting is on, tnftp will ask you to confirm that the last argument is the local file for the mls output. 🫠
  • mlsd [remote-path] 🤖 — Shows the contents of remote-path in a machine-parsable form, using MLSD. If you don't give a path, it defaults to the current directory. You can change how it displays with remopts mlst .... 💻
  • mlst [remote-path] 🔍 — Shows details about remote-path in a machine-parsable form, using MLST. Without a path, it defaults to the current directory. You can change the display format with remopts mlst .... 🧾
  • mode mode-name 🚗 — Sets the file transfer mode to mode-name. The default, and the only supported mode, is stream. 🌊
  • modtime remote-file 🕰️ — Shows the last modification time of the file on the remote machine, in RFC 2822 format. ⏳
  • more file 📜 — Same as page. 💅
  • mput local-files 📤 — Expands wild cards in the local-files you list, then does a put for each file in the resulting list. Check glob for the details on filename expansion. The resulting filenames then get processed according to the ntrans and nmap settings. 🍓
  • mreget remote-files 🔁 — Works just like mget, except it does a reget instead of a get. 🦋
  • msend local-files 📨 — Same as mput. 💌
  • newer remote-file [local-file] 🆕 — Only gets the file if the remote file's modification time is more recent than the file on your current system. If the file doesn't exist on your system, the remote file counts as newer. Otherwise, this command acts exactly like get. ✨
  • nlist [remote-path [local-file]] 📋 — Same as ls. 🎀
  • nmap [inpattern outpattern] 🗺️ — Sets or unsets the filename mapping mechanism. No arguments? It gets unset. With arguments, remote filenames get mapped during mput commands and during put commands that don't have a specified remote target filename. Local filenames get mapped during mget commands and get commands that don't have a specified local target filename. This is super handy when you're connecting to a non-Unix remote computer with different file naming conventions or habits. The mapping follows the pattern set by inpattern and outpattern. 💖

inpattern is a template for incoming filenames. These may already have been processed according to the ntrans and case settings. You make variables by including $1, $2, ..., $9 in inpattern. Use \ to stop that special treatment of the $ character. Every other character is treated literally, and those characters are used to work out the values of the variables. For example, with inpattern $1.$2 and the remote filename mydata.data, $1 would be mydata and $2 would be data. 🧩

outpattern decides the final mapped filename. The sequences $1, $2, ..., $9 get replaced by whatever values came out of the inpattern template. The sequence $0 gets replaced by the original filename. There's also the sequence [seq1,seq2], which becomes seq1 if seq1 isn't a null string, and otherwise becomes seq2. For example, this command:

nmap $1.$2.$3 [$1,$2].[$2,file]

would give the output filename myfile.data for the input filenames myfile.data and myfile.data.old, myfile.file for the input filename myfile, and myfile.myfile for the input filename .myfile. Spaces can go in outpattern too, like in this example:

nmap $1 sed s/  *$// > $1

Use \ to stop special treatment of the $, [, ], and , characters. 🫶✨

Okay so bestie, we're picking up right where the commands list left off 💅✨

  • ntrans [inchars [outchars]] — filename character translation time! 🦋 Use this to set up (or unset) a swap for filename characters. If you don't give it any arguments, the translation gets switched off. If you do give arguments, characters in remote filenames get swapped during mput and put commands that don't have a remote target filename. Local filenames get the same treatment during mget and get commands that don't have a local target filename. It's super handy when you're talking to a non-Unix remote computer with different naming conventions or habits 🌸. Any character in a filename that matches one in inchars gets replaced by the matching character in outchars. And if a character's spot in inchars is further along than the length of outchars, that character just gets deleted from the filename 💀.
  • open host [port] — connect to the FTP server at the host you name 💖. You can add a port number if you want tnftp to knock on a specific port instead. If set auto-login is on (which it is by default), tnftp will also try to log you in automatically 🫶 (see below).
  • page file — grabs file from the remote machine and shows it using whatever program you've set in the set pager option 📖.
  • passive [auto] — flips passive mode on or off when you don't give it anything 🧚. If you type auto, it acts like FTPMODE is set to ‘auto’. When passive mode is on (the default), tnftp sends a PASV command for every data connection instead of a PORT command. With PASV, the remote server opens a port for the data connection and tells you the address, then it listens there and you connect to it. With the old-school PORT command, the client is the one listening and it sends that address to the server, which connects back 🔄. Passive mode is a lifesaver when you're going through a gateway router or host that controls which direction traffic flows 🛡️. (Heads up: RFC 1123 says FTP servers have to support PASV, but some of them just don't 😭.)
  • pdir [remote-path] — runs dir [remote-path] and shows the result through the program set in the set pager option 📂.
  • pls [remote-path] — runs ls [remote-path] and pipes the result to your set pager program 📃.
  • pmlsd [remote-path] — runs mlsd [remote-path] and shows the result with your set pager program 🌷.
  • preserve — toggles whether modification times get kept on the files you retrieve 🕰️.
  • progress — toggles the transfer progress bar 📊. The bar gets turned off for any transfer where local-file is ‘-’ or a command that starts with ‘|’. Check out “FILE NAMING CONVENTIONS” for more on that 👀. Heads up, turning progress on also disables hash 🙅‍♀️.
  • prompt — toggles interactive prompting 💬. Prompting happens during multi-file transfers so you can pick which files to grab or store. If prompting is off (default is on), mget and mput will transfer every file, and mdelete will delete every file 💥. When prompting is on, these answers are available at the prompt:
    • a — say yes to the current file, and automatically say yes to any remaining files for the current command 🙌.
    • n — say no and skip this file 🙅‍♀️.
    • p — say yes to the current file and turn off prompt mode, same as if you'd typed prompt off 🔕.
    • q — stop the current operation entirely 🛑.
    • y — say yes and transfer the file ✅.
    • ? — show a help message 🆘.

Literally any other response counts as a yes for the current file 💅.

  • proxy ftp-command — runs an FTP command over a secondary control connection 👑. This is the move when you want to be connected to two remote FTP servers at once and move files between them. Your first proxy command should be an open, which sets up the secondary control connection 🔗. Type proxy ? to see every FTP command you can run on the secondary connection 🔍. A few commands act differently with proxy in front: open won't define new macros during auto-login, close won't erase existing macro definitions, get and mget move files from the host on the primary control connection to the host on the secondary one, and put, mput, and append move files from the secondary host to the primary one 🔁. Third-party transfers only work if the server on the secondary control connection supports the FTP PASV command 🫠.
  • put local-file [remote-file] — stores a local file on the remote machine 📤. If you skip remote-file, the local file name gets used, after running through any ntrans or nmap settings to become the remote name 🏷️. The transfer uses your current type, format, mode, and structure settings 🎀.
  • pwd — prints the name of the current working directory on the remote machine 📍.
  • quit — just a synonym for bye 👋.
  • quote [arg ...] — sends whatever arguments you give it, verbatim, straight to the remote FTP server 🗣️.
  • rate direction [maximum [increment]] — throttles the maximum transfer rate to maximum bytes per second 🐢. If maximum is 0, the throttle gets switched off 🚫. direction can be one of these:
    • all — both directions 🔀.
    • get — incoming transfers ⬇️.
    • put — outgoing transfers ⬆️.

maximum can be tweaked on the fly by increment bytes (default: 1024) every time one of these signals arrives 📡:

  • SIGUSR1 — bumps maximum up by increment bytes ⬆️.
  • SIGUSR2 — knocks maximum down by increment bytes. The result has to stay a positive number ⚠️.

If you don't supply maximum, you'll see the current throttle rates instead 👀.

Note: rate isn't implemented yet for ascii mode transfers 🚧.

  • rcvbuf size — sets the size of the socket receive buffer to size 🪣.
  • recv remote-file [local-file] — a synonym for get 🔁.
  • reget remote-file [local-file] — basically get, but with a twist 🌈. If local-file already exists and is smaller than remote-file, tnftp assumes it's a partial copy of remote-file and continues the transfer from where it apparently failed. This is perfect for huge files over flaky networks that keep dropping connections 🥹.
  • remopts command [command-options] — sets options on the remote FTP server for command to command-options (what happens when they're missing depends on the command) 🛠️. The remote FTP commands known to support options include: MLST (used for MLSD and MLST) 🧾.
  • rename [from [to]] — renames the file from on the remote machine to the name to ✏️.
  • reset — clears the reply queue 🧹. This re-syncs the command and reply sequencing with the remote FTP server. You might need this after the remote server breaks the FTP protocol 😤.
  • restart marker — restarts the very next get or put at the marker you name 🔖. On Unix systems, the marker is usually a byte offset into the file 🔢.
  • rhelp [command-name] — asks the remote FTP server for help 🆘. If you give a command-name, it gets passed along to the server too 📨.
  • rmdir directory-name — deletes a directory on the remote machine 🗑️.
  • rstatus [remote-file] — with no arguments, shows the status of the remote machine 📡. If you name a remote-file, it shows the status of that file on the remote machine instead 📄.
  • runique — toggles storing files locally under unique filenames 🦄. If a file already exists with the same name as the target local filename for a get or mget, a .1 gets appended to the name. If that name is also taken, a .2 gets appended to the original name instead. This keeps going up to .99, and if it gets that far, an error message prints and the transfer doesn't happen 😱. The generated unique filename gets reported back to you. Note that runique won't touch local files generated from a shell command (see below) 🐚. The default is off.
  • send local-file [remote-file] — a synonym for put 📮.
  • sendport — toggles the use of PORT commands 🔌. By default, tnftp tries to use a PORT command when setting up a connection for each data transfer. Using PORT commands can keep things from lagging when you're doing lots of file transfers 🏃‍♀️. If the PORT command fails, tnftp falls back to the default data port. When PORT commands are disabled, tnftp won't try to use them for any data transfer. This is useful for certain FTP implementations that ignore PORT commands but, incorrectly, say they've been accepted 🙃.
  • set [option value] — sets option to value ⚙️. If you don't give option and value, you'll see every option and its current value 📋. The currently supported options are:
    • anonpass — defaults to $FTPANONPASS 🔑.
    • ftp_proxy — defaults to $ftp_proxy 🌐.
    • http_proxy — defaults to $http_proxy 🌍.
    • https_proxy — defaults to $https_proxy 🔐.

no_proxy — Defaults to $no_proxy. 🌸

  • pager — Defaults to $PAGER. 📖
  • prompt — Defaults to $FTPPROMPT. 💬
  • rprompt — Defaults to $FTPRPROMPT. 🫶
  • sslnoverify — Defaults to $FTPSSLNOVERIFY. 🔐
  • site [arg ...] — Whatever you type here gets shipped, word for word, to the remote FTP server as a SITE command. No edits, no cap. 🚀
  • size remote-file — Asks the remote machine how big remote-file is. 📏
  • sndbuf size — Sets the size of the socket send buffer to size. 📦
  • status — Shows you the current status of tnftp. Main character check! 👑
  • struct struct-name — Sets the file transfer structure to struct-name. The default, and honestly the only supported one, is ‘file’. 🧱
  • sunique — Flips storing files on the remote machine under unique file names on or off. Heads up: the remote FTP server has to support the FTP STOU command for this to finish successfully. The server will tell you the unique name it picked. The default is off. 🦋
  • system — Shows what type of operating system is running on the remote machine. 💻
  • tenex — Sets the file transfer type to whatever is needed to talk to TENEX machines. Very retro, very iconic. 🕰️
  • throttle — Just a synonym for rate. Same energy, different name. 🫠
  • trace — Toggles packet tracing. 🕵️‍♀️
  • type [type-name] — Sets the file transfer type to type-name. If you don't give it one, it prints the current type instead. The default type is network ASCII. 🔤
  • umask [newmask] — Sets the default umask on the remote server to newmask. If you leave newmask out, the current umask gets printed. 🙈
  • unset option — Unsets option. Check out set if you want the full tea. ☕
  • usage command — Prints the usage message for command. Forgot how something works? This is your rescue. 🆘
  • user user-name [password [account]] — Introduces you to the remote FTP server. If you don't pass a password and the server wants one, tnftp will ask you for it, and local echo gets turned off so nobody can peek over your shoulder 🙈🔒. If you skip the account field and the server needs one, you'll get prompted for that too. If you DO give an account, an account command gets relayed to the remote server after the login sequence finishes, but only if the server didn't need it to log you in. Unless tnftp was started with “auto-login” disabled, this whole dance happens automatically the first time you connect. ✨
  • verbose — Toggles verbose mode. When it's on, every response from the FTP server gets shown to you. Also, if verbose is on when a transfer finishes, you'll get stats on how efficient the transfer was. By default, verbose is on. 📣
  • xferbuf size — Sets the size of the socket send and receive buffers to size. 🎀
  • ? [command] — A synonym for help. Literally just a shortcut. 💅

Command arguments with embedded spaces can be wrapped in quote ‘"’ marks, so the shell doesn't split them up on you. 🧩

Commands that toggle settings can also take an explicit on or off argument if you want to force the setting one way or the other. No guessing needed! 🎯

Commands that take a byte count (like hash, rate, and xferbuf) support an optional suffix that changes how the number gets read. Here are the suffixes, bestie:

  • b — Causes no modification. (Optional, so you don't even need to type it 💜)
  • k — Kilo! Multiplies the argument by 1024. 🍓
  • m — Mega! Multiplies the argument by 1048576. 🌈
  • g — Giga! Multiplies the argument by 1073741824. 🔥
😭 Heads up: if tnftp gets a SIGINFO (check the status argument of stty(1) for that one) or a SIGQUIT signal while a transfer is happening, it'll dump the current transfer rate statistics to the standard error output. The format matches the standard completion message, so you'll feel right at home. 📊

✨ AUTO-FETCHING FILES ✨

Okay so, on top of the regular commands, this version of tnftp has an auto-fetch feature that is literally so good. 🤩 To turn it on, just pass a list of hostnames and/or files on the command line. Easy peasy. 🫶

These are the formats that count as valid syntax for an auto-fetch element:

  • [user@]host:[path][/] — The “Classic” FTP format. 📮

If path has a glob character in it and globbing is enabled (see glob), tnftp does the equivalent of mget path. 🪄

If the directory part of path has no globbing characters, the file gets stored locally with the basename(1) of path, in the current directory. Otherwise, the full remote name is used as the local name, relative to the local root directory. 🗂️

  • ftp://[user[:password]@]host[:port]/path[/][;type=type] — An FTP URL! It gets retrieved with the FTP protocol as long as set ftp_proxy isn't defined. If it IS defined, the URL gets transferred over HTTP through the proxy set in ftp_proxy. If ftp_proxy isn't defined and you gave a user, tnftp logs in as that user. You can pass a password too, and if you don't, you'll get prompted for one. 🔑

If the URL ends with a ;type=A or ;type=I suffix, the transfer happens as ascii or binary (respectively). The default transfer type is binary. 🤖

To play nice with RFC 3986, tnftp reads the path part of an ftp:// auto-fetch URL like this:

  • The / right after host[:port] is treated as a separator before the path, not as part of the path itself. ✂️
  • The path is read as a /-separated list of name components. For every component except the last one, tnftp does the equivalent of a cd command. For the last component, it does the equivalent of a get command. 🧭
  • Empty name components (which happen with // inside the path, or with an extra / at the very start) will cause the equivalent of a cd command with no directory name. This is unlikely to be useful, so maybe don't count on it. 🙃
  • Any %XX codes (per RFC 3986) inside the path components get decoded, where XX is a character code in hexadecimal. The decoding happens after the path is split into components, but before each component gets used in the equivalent of a cd or get command. Some popular codes: %2F (which is /) and %7E (which is ~). 🌸

Here's what that means in practice:

  • The path is read relative to the default login directory of the specified user, or of the anonymous user. If you need the / directory, start your path with %2F. If you need a user's home directory (and the remote server supports that syntax), start your path with %7Euser/. For example, to grab /etc/motd from localhost as the user myname with the password mypass, use ftp://myname:mypass@localhost/%2fetc/motd 🏠
  • You can control the exact cd and get commands by choosing carefully where to put / and where to put %2F (or %2f). For example, these URLs line up with the equivalent commands listed next to them:
ftp://host/dir1/dir2/file         cd dir1, cd dir2, get file.

ftp://host/%2Fdir1/dir2/file      cd /dir1, cd dir2, get file.

ftp://host/dir1%2Fdir2/file       cd dir1/dir2, get file.
  • You need the right access permissions for every intermediate directory used in the equivalent of a cd command. No permissions, no party. 🚪
  • http://[user[:password]@]host[:port]/path — An HTTP URL, retrieved with the HTTP protocol. If set http_proxy is defined, it gets used as a URL to an HTTP proxy server. If HTTP authorization is needed to retrieve path, and a user (and optionally a password) is in the URL, those get used for the first authentication attempt. 🌐
  • https://[user[:password]@]host[:port]/path — An HTTPS URL, retrieved with the HTTPS protocol. If set https_proxy is defined, it gets used as a URL to an HTTPS proxy server. If HTTPS authorization is needed to retrieve path, and a user (and optionally a password) is in the URL, those get used for the first attempt to authenticate. ⚠️ There is currently no certificate validation and verification, so be careful with anything sensitive. 🔓
  • file:///path — A local URL, copied from /path on the local host. 📁
  • about:topic — Displays information about topic. No file is retrieved for this auto-fetched element. Supported values include: 📚
    • about:ftp — Information about tnftp. 🎀
    • about:version — The version of tnftp. Super useful to include when you're reporting problems, so bring it! 🐛

Unless noted otherwise above, and if -o output is not given, the file gets stored in the current directory as the basename(1) of path. Note that if an HTTP redirect comes back, the fetch gets retried using the new target URL the server supplied, with a matching new path. 🔁 Using an explicit -o output is recommended so you don't accidentally write to some unexpected file name. 🙏

If a classic format or an FTP URL format has a trailing / or an empty path component, tnftp will connect to the site and cd to the directory given as the path, then leave you in interactive mode, ready for more input. This won't work if set ftp_proxy is being used. 🙅‍♀️

Direct HTTP transfers use HTTP 1.1. Proxied FTP and HTTP transfers use HTTP 1.0. 💅

If you pass -R, all auto-fetches that don't go through the FTP or HTTP proxies will be restarted. For FTP, this is done by using reget instead of get. For HTTP, it's done with the Range: bytes= HTTP/1.1 directive. Resume game strong! 🔄

If WWW or proxy WWW authentication is required, you'll be prompted to enter a username and password to authenticate with. 🔐

When you're specifying IPv6 numeric addresses in a URL, you need to wrap the address in square brackets. E.g.: ftp://[::1]:21/. This is because colons show up in IPv6 numeric addresses AND act as the separator for the port number, so the brackets keep everything from getting confused. 🧠✨

✨ ABORTING A FILE TRANSFER ✨

okay so if you need to bail on a transfer, just hit the terminal interrupt key (usually Ctrl-C) 🛑. Sending transfers get halted immediately. Receiving transfers get halted by sending an FTP protocol ABOR command to the remote server and then tossing out any extra data that comes in 🗑️. How fast that happens depends on how well the remote server handles ABOR processing 🐢. If the remote server doesn't support the ABOR command at all, the prompt won't come back until the server has finished sending the requested file, so just vibe and wait 🫠.

⚠️ bestie, if you hit the terminal interrupt key while tnftp is waiting on the remote server's reply to the ABOR, the connection gets closed 💀. This is different from the traditional behaviour (which ignores the terminal interrupt during this phase), but it's considered more useful ✨.

🎀 FILE NAMING CONVENTIONS 🎀

okay so every file you pass as an argument to a tnftp command gets processed using these rules 📝:

  1. If the file name is -, then stdin (for reading) or stdout (for writing) gets used 🎯.
  2. If the first character of the file name is |, the rest of the argument is treated as a shell command 🐚. tnftp then forks a shell, using popen(3) with the argument you gave it, and reads from (or writes to) the stdout (or stdin) 🪄. If the shell command has spaces in it, the argument has to be quoted, like "| ls -lt". A super useful example of this is dir "" |more 💅.
  3. If the above checks don't match and globbing is enabled, local file names get expanded using the rules from csh(1); see the glob command 🌀. If the tnftp command expects a single local file (like put), only the first filename the globbing produces gets used ☝️.
  4. For mget commands and get commands with no local file name given, the local file name is the remote file name 📥. That name can get altered by a case, ntrans, or nmap setting. The resulting name may then get altered again if runique is on 🔁.
  5. For mput commands and put commands with no remote file name given, the remote file name is the local file name 📤. That can get altered by an ntrans or nmap setting. The resulting name may then get altered by the remote server if sunique is on 🙈.

🦋 FILE TRANSFER PARAMETERS 🦋

the FTP spec has a ton of parameters that can affect a file transfer, so buckle up 🫶. The type can be one of “ascii”, “image” (binary), “ebcdic”, and “local byte size” (mostly for PDP-10's and PDP-20's, lol) 🖥️. tnftp supports the ascii and image types, plus local byte size 8 for tenex mode transfers ✨.

tnftp only supports the default values for the remaining file transfer parameters: mode, form, and struct 💁‍♀️. no notes, no drama.

📒 THE .netrc FILE 📒

okay so the .netrc file holds the login and initialization info used by the auto-login process 🔑. It lives in the user's home directory, unless you override it with the -N netrc option, or set it in the NETRC environment variable 🏠. These tokens are recognized, and they can be separated by spaces, tabs, or new-lines 🧩:

  • machine name — identifies a remote machine name 🖥️. The auto-login process searches the .netrc file for a machine token that matches the remote machine you gave on the tnftp command line or as an open command argument 🔍. Once it finds a match, it processes the following .netrc tokens, and stops when it hits the end of the file or another machine or default token 🛑.
  • default — basically the same as machine name, except default matches any name 🌍. There can be only one default token, and it has to come after all the machine tokens 📌. This is normally used like this:
default login anonymous password user@site

which gives you an automatic anonymous FTP login to machines not listed in .netrc 🎉. You can override this by using the -n flag to disable auto-login 🙅‍♀️.

  • login name — identifies a user on the remote machine 👤. If this token is there, the auto-login process starts a login with the name you specified 🚪.
  • password string — supplies a password 🤫. If this token is there, the auto-login process supplies the string if the remote server asks for a password during login 🔐. Heads up: if this token is in the .netrc file for any user other than anonymous, tnftp will abort the auto-login process if the .netrc file is readable by anyone besides the user 🚨.
  • account string — supplies an extra account password 💳. If this token is there, the auto-login process supplies the string if the remote server asks for an additional account password 🙋‍♀️. If the server doesn't ask for one, the auto-login process starts an ACCT command instead 🔄.
  • macdef name — defines a macro 🧪. This token works just like the tnftp macdef command does 🤝. The macro gets defined with the name you give it, and its contents start on the next .netrc line and keep going until a blank line (consecutive new-line characters) shows up 📜. Like the other .netrc tokens, a macdef only applies to the machine definition right before it 📍. A macdef entry can't be shared by multiple machine definitions, so you have to define it after each machine you want it to work with 👯. If a macro named init is defined, it gets automatically executed as the last step in the auto-login process ⭐. For example:
default
macdef init
epsv4 off

and then a blank line after it, so the macro knows where to stop 🫧.

💻 COMMAND LINE EDITING 💻

tnftp supports interactive command line editing through the editline(3) library 🪄. You turn it on with the edit command, and it's enabled by default if input is coming from a tty ✅. You can recall and edit previous lines with the arrow keys, and other GNU Emacs-style editing keys work too 🧠.

The editline(3) library gets configured with a .editrc file, so check out editrc(5) for more info 📖.

There's also an extra key binding that gives tnftp context sensitive command and filename completion (including remote file completion) 🤩. To use it, bind a key to the editline(3) command ftp-complete. By default this is bound to the TAB key ⌨️.

🌸 COMMAND LINE PROMPT 🌸

by default, tnftp shows the user a command line prompt of ftp> 💬. You can change that with the set prompt command 🎨.

You can also show a prompt on the right side of the screen (after the command input) with the set rprompt command 👀.

The following formatting sequences get replaced by the info they stand for 🧁:

  • %/ — the current remote working directory 📂.
  • %c[[0]n], %.[[0]n] — the trailing component of the current remote working directory, or n trailing components if a digit n is given 🧩. If n begins with 0, the number of skipped components goes in front of the trailing component(s), formatted as /<number>trailing (for %c) or ...trailing (for %.) 🔢.
  • %M — the remote host name 🖥️.
  • %m — the remote host name, up to the first dot . 🪚.
  • %n — the remote user name 👤.
  • %% — a single percent character % 💯.

🌈 ENVIRONMENT 🌈

tnftp uses the following environment variables, so these are the ones to know 🫶.

  • FTPANONPASS — the password to send in an anonymous FTP transfer 🔓. It defaults to “`whoami`@”.
  • FTPMODE — overrides the default operation mode 🔀. Supported values are:
    • active — active mode FTP only 📣.
    • auto — automatic determination of passive or active (this is the default) 🤖.
    • gate — gate-ftp mode 🚪.
    • passive — passive mode FTP only 🤫.
  • FTPPROMPT — the command-line prompt to use 💬. It defaults to ftp> . Check out “COMMAND LINE PROMPT” for more info 👆.
  • FTPRPROMPT — the command-line right side prompt to use 👉. It defaults to an empty string. Check out “COMMAND LINE PROMPT” for more info 👆.
  • FTPSERVER — the host to use as the gate-ftp server when gate is enabled 🚪.
  • FTPSERVERPORT — the port to use when connecting to the gate-ftp server when gate is enabled 🔌. The default is the port returned by a getservbyname(3) lookup of “ftpgate/tcp” 🔍.
  • FTPUSERAGENT — the value to send for the HTTP User-Agent header 🕵️‍♀️.
  • FTPSSLNOVERIFY — set this to 1 to not verify SSL certificates 🙈.
  • HOME — used for the default location of a .netrc file, if one exists 🏡.
  • NETRC — an alternate location of the .netrc file 📍.
  • PAGER — used by various commands to display files 📄. It defaults to more(1) if it's empty or not set 📖.
  • SHELL — used for the default shell 🐚.
  • ftp_proxy — the URL of the FTP proxy to use when making FTP URL requests 🌐. If it's not defined, the standard FTP protocol gets used instead 🔁.

See http_proxy for further notes about proxy use 👀.

  • http_proxy — the URL of the HTTP proxy to use when making HTTP URL requests 🌍. If proxy authentication is required and there's a username and password in this URL, they get used automatically in the first attempt to authenticate to the proxy 🔑.

If “unsafe” URL characters are needed in the username or password (for example @ or /), encode them with RFC 3986 %XX encoding 🧼.

⚠️ the use of a username and password in ftp_proxy and http_proxy may be incompatible with other programs that use them (such as lynx(1)) 💀.
📝 NOTE: this is not used for interactive sessions, only for command-line fetches 🎯.
  • https_proxy — the URL of the HTTPS proxy to use when making HTTPS URL requests 🔒.

See http_proxy for further notes about proxy use 👀.

  • no_proxy — a space or comma separated list of hosts (or domains) that should not be proxied 🙅‍♀️. Each entry can have an optional trailing :port, which restricts the matching to connections to that port 🎯.

✨ EXTENDED PASSIVE MODE AND FIREWALLS ✨

okay so bestie, some firewall setups just don't vibe with tnftp using extended passive mode 🙈 if even a plain ls seems to hang forever after printing something like this:

229 Entering Extended Passive Mode (|||58551|)

that's your sign 🚩 you need to turn extended passive mode off with epsv4 off. the "The .netrc File" section above has an example of how to make that happen automatically so you never have to think about it again 🫶

🦋 SEE ALSO 🦋

okay here's where to go for more info, no cap 💜

📜 STANDARDS 📜

tnftp really tries to be compliant with these bad boys 👑

  • RFC 959 — File Transfer Protocol
  • RFC 1123 — Requirements for Internet Hosts - Application and Support
  • RFC 1635 — How to Use Anonymous FTP
  • RFC 2389 — Feature negotiation mechanism for the File Transfer Protocol
  • RFC 2428 — FTP Extensions for IPv6 and NATs
  • RFC 2616 — Hypertext Transfer Protocol -- HTTP/1.1
  • RFC 2822 — Internet Message Format
  • RFC 3659 — Extensions to FTP
  • RFC 3986 — Uniform Resource Identifier (URI)

🌈 HISTORY 🌈

the tnftp command first showed up in 4.2BSD, iconic origin story ✨

okay but then it got a whole glow-up 💅 features like command line editing, context sensitive command and file completion, a dynamic progress bar, automatic fetching of files and URLs, modification time preservation, transfer rate throttling, a configurable command line prompt, and a bunch of other enhancements over the standard BSD tnftp were added in NetBSD 1.3 and later releases. the main brain behind all that was Luke Mewburn ⟨lukem@NetBSD.org⟩ 🧚

IPv6 support came from the WIDE/KAME project 🌸 heads up though, it might not be in every non-NetBSD version of this program, since it depends on whether the operating system supports IPv6 in a similar manner to KAME.

🐛 BUGS 🐛

not gonna lie, a lot of commands only work right if the remote server behaves properly 💀

the 4.2BSD ascii-mode transfer code had a carriage return bug, and that's been fixed 🙏 but the fix can mess up binary files moving to and from 4.2BSD servers using the ascii type. to dodge this, use the binary image type instead.

also tnftp assumes every IPv4 mapped address (IPv6 addresses that look like ::ffff:10.1.1.1) points to an IPv4 destination that AF_INET sockets can handle. in some IPv6 network setups, though, that's just not true 😭 in those environments, IPv4 mapped addresses have to be passed straight to AF_INET6 sockets. for example, if your site uses a SIIT translator for IPv6-to-IPv4 translation, tnftp can't support that configuration, sorry bestie 🥺

Manpage brought to you by Debian, last updated February 25, 2023, for TNFTP(1) 🎀💖 stay hydrated and keep those transfers flowing, bestie ✨🦋

📦 where this page comes from