FTP-UPLOAD(1p)

💖 FTP-UPLOAD(1p) 💖

okay bestie so this is ftp-upload, from the User Contributed Perl Documentation (section 1p), and it's genuinely one of those little tools that just works if you let it. sit down, grab a strawberry, we're doing this together 🍓

✨ NAME ✨

ftp-upload — batch transfer local files to an FTP server 🦋

🌸 SYNOPSIS 🌸

ftp-upload [any-switch]... {[repeatable-switch]... file...}...

👑 DESCRIPTION 👑

so ftp-upload sends your local files to an FTP server. that's it, that's the whole vibe. 💅

it is not interactive — it's built to live inside scripts, which honestly is its main character era. it's super disciplined about its exit value (like, it will not play games with you about whether it succeeded), and by default it doesn't print informational messages at all. silent, mysterious, iconic. 🎀

now, there are two kinds of switches, and this is the part where people get confused so pay attention bestie:

• Initial switches — these have to come before any filenames. they affect the whole session as one big thing.
• Repeatable switches — these can be sprinkled in between the file names. they affect the transfer of whatever files come after them on the command line.

---

💅 OPTIONS 💅

🌈 Initial switches

these have to be used before any file names listed on the command line. no negotiating. 🙈

• --debug — turn debugging on. 👀
• --help — show the usage message and die. dramatic, but make it helpful.
• --ignore-quit-failure — don't complain and don't set a failure exit code just because the QUIT command fails. why would you ever need this? because some servers, in blatant disregard of RFC 959, close the command channel the moment you send them an ABOR command. rude behavior, honestly. 💀
• -v, --verbose — print informational messages to stdout. the opposite of its default introvert energy.
• --version — show the version number and exit. quick lil flex. ✨

🦋 Initial switches which specify connection information

these also have to be used before any file names on the command line. they're the ones that describe how the FTP connection itself gets set up. 🔌

• --account account — the account to use when logging into the remote system. this is distinct from the user name used to log in. few systems actually need it. there is no default.
• -h, --host host — the host to connect to. there is no default, so like… you have to pass this switch. it's not optional, bestie, it's the whole point. 😭
• --passive — force the use of passive (PASV) transfers. passive transfers are required with some firewall configurations, but if you're in that situation you'd honestly do better configuring Net::FTP so it knows when to use them (see Net::Config). however, if you need passive transfers with certain (broken) servers, this switch is your best bet. alternatively you can set $FTP_PASSIVE to 1 in the environment (see Net::FTP).
• --no-passive — force active mode transfers. active mode is the default, so you only need this if your Net::Config or $FTP_PASSIVE turned passive mode on.
• --password pw — the password used to login. the default is your email address.

⚠️ do NOT put a real (secret) password here. on most systems, anybody on the machine can see the arguments you pass to your commands. use one of the other password-setting switches instead. i'm begging you. 🙏

• -s, --password-stdin — read the password from standard input. no prompt gets printed, and a single line is read. most people use this switch for the password, and honestly, slay. eg,

echo 3x9sjJJh | ftp-upload -sh $host -u $user $file

using echo this way is safe where --password isn't — as long as the echo command is built in to the shell. 🐚

• --password-fd fd — like --password-stdin, except it reads the password from the file descriptor numbered fd.

ftp-upload -h $host -u $user --password-fd=3 3<$pw_file $file

• -u, --user user — the user name to use when logging in. the default is "anonymous". ✨

🎀 Repeatable switches

these can be used anywhere on the command line (except after the last file name, obviously 🙄). they affect the transfer of the files listed after them.

• --as remote-name — normally a file gets transferred using the same name it has locally. use this switch and the next file transferred will be called remote-name on the other host instead.

ftp-upload --host $host --as index.htm index.html

• -a, --ascii — do the transfers in ASCII mode.
• -b, --binary — do the transfers in binary mode. this is the default. 🔥
• -d, --dir dir — change directory to dir on the FTP server before continuing. you can use this multiple times between files, and ftp-upload will chdir once for each time you specify it. using ".." as the dir causes an FTP "CDUP" to be done instead of a "CWD". 🗂️
• --full-path — normally uploaded files go into the current directory on the remote host, even when the local file name you gave contains slashes. eg, if you say

ftp-upload -h $host /etc/motd

ftp-upload will upload the file as motd, not /etc/motd. this differs from how the standard ftp program works, and it also differs from how ftp-upload worked before version 1.3. if you specify --full-path, you get the other behavior. a request to upload dir/file tells the server to store dir/file rather than file. when you use --as, the --full-path setting doesn't matter. --full-path only tells the program what name to use when it's choosing the name.

• --no-full-path — disable --full-path. this is the default.
• -l, --ls — try to get a remote directory listing of the files after transferring them. i say "try" because there is no guaranteed way to do this with the FTP protocol. the command it runs is "LIST file". this will generally work if file doesn't contain any special characters.
• -L, --no-ls — disable the --ls behavior.
• --tmp-none — transfer files directly, don't do anything special to try to keep them from appearing under their real names on the remote machine until the transfer is finished. each file is transferred with a single simple "STOR". this is the default.
• --tmp-samedir — transfer files to the remote machine using a temporary name, then rename them when the transfer finishes. this won't work if the remote server doesn't give a recognizable response to the "STOU" command. 😬 if the server's response to "STOU" isn't recognized by Net::FTP but is reasonable, Graham Barr might be willing to change Net::FTP to recognize it. if you like, you can send the --debug output to the author and he'll coordinate such requests. 🤝
• --tmp-dir dir — transfer files to dir on the remote host, then rename them when the transfer is complete. this is safer than --tmp-samedir because it doesn't use "STOU", and so it works with more servers.

ftp-upload -h $host --tmp-dir incoming $file

• --tmp-format fmt — transfer files to sprintf(fmt, file base name), then rename them when the transfer is complete. like --tmp-dir, this is safer than --tmp-samedir because it doesn't use "STOU", so it works with more servers.

ftp-upload -h $host --tmp-format tmp.%s $file

---

🌟 AUTHOR 🌟

Roderick Schertler <roderick@argon.org> — absolute legend, we stan. 🫶

---

okay that's the whole page, bestie, you're officially fluent 💖 this one's from perl v5.36.0, dated 2022-11-21, so go forth and upload responsibly, and please don't put your real password on the command line. mwah 💅✨