S3PUT(1p)

💾 S3PUT(1p) — the write-an-S3-item era 💾

okay bestie, so this is s3put, a User Contributed Perl Documentation situation, living in section 1p of the manual. she's a lil script that reads your stdin and yeets it up into an S3 item. that's the whole vibe. let's get into it 🫶

---

✨ NAME ✨

s3put — Write an S3 item

like. that's it. that's the girl. she writes an S3 item. 👑

---

🌸 SYNOPSIS 🌸

s3put [options] [ bucket/item ...]

 Options:
   --access-key    AWS Access Key ID
   --secret-key    AWS Secret Access Key
 Environment:
   AWS_ACCESS_KEY_ID
   AWS_ACCESS_KEY_SECRET

so you run her with whatever options, and then optionally a bucket/item or a few of them, and she does her thing. the options and the environment variables are your two ways of telling her who you are. more on that below, stay with me 🧚

---

💅 OPTIONS 💅

• --help — prints a short lil help message and then dips. exits immediately. bye! 👋
• --man — prints the whole manual page and exits. that's the long version, the one you're reading rn, iconic behavior fr.
• --verbose — tells you what's happening as it's happening. output as she goes, no mystery, we love transparency.
• --access-key and --secret-key — these specify the "AWS Access Key Identifiers" for the AWS account. --access-key is the "Access Key ID", and --secret-key is the "Secret Access Key". lowkey think of them as the username and password for your AWS account, except they're the kind of username and password you should keep confidential, like, do not be posting these, bestie 😭

The access keys MUST be specified, either via these command line parameters, or via the AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY_SECRET environment variables. no keys, no service. that's the rule.

Specifying them on the command line overrides the environment variables. command line stays winning, periodt.

• --secure — uses SSL/TLS HTTPS to communicate with the AWS service instead of HTTP. she's putting on the little padlock 🎀🔒

---

🌈 ENVIRONMENT VARIABLES 🌈

• AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY_SECRET — specify the "AWS Access Key Identifiers" for the AWS account. AWS_ACCESS_KEY_ID contains the "Access Key ID", and AWS_ACCESS_KEY_SECRET contains the "Secret Access Key". these are effectively the "username" and "password" to the AWS service, and should be kept confidential. literally treat them like your diary, except worse if someone finds them 💀

The access keys MUST be specified, either via these environment variables, or via the --access-key and --secret-key command line parameters. those are the only two doors, pick one.

If the command line parameters are set, they override these environment variables. so if both exist, cmdline wins, no debate, iykyk.

---

🎀 CONFIGURATION FILE 🎀

okay so here's the tea — the configuration options get read from the file ~/.s3-tools, if it exists. if it doesn't exist, whatever, she just moves on, no drama. 💖

the format is the same as the command line options, with one option per line. for example, the file could contain:

--access-key <AWS access key>
--secret-key <AWS secret key>
--secure

this example configuration file would specify the AWS access keys and that a secure connection using HTTPS should be used for all communications. so it's like a lil pre-set vibe for every single run. obsessed. ✨

---

💜 DESCRIPTION 💜

Reads stdin, and writes it to an S3 item.

that's the entire plot. she takes what you pipe into her and she puts it in S3. main character energy tbh 🌟

---

💀 BUGS 💀

Report bugs to Mark Atwood mark@fallenpegasus.com. he wants to know, bestie, tell him.

and now the list of things that are lowkey cursed, in the original's own words:

• Occasionally the S3 service will randomly fail for no externally apparent reason. When that happens, this tool should retry, with a delay and a backoff. (emphasis on should — as in, that's a known gap, not a feature. no cap 😭)
• Access to the S3 service can be authenticated with a X.509 certificate, instead of via the "AWS Access Key Identifiers". This tool should support that. (again: should. doesn't. yet.)
• It might be useful to be able to specify the "AWS Access Key Identifiers" in the user's ~/.netrc file. This tool should support that. (you see the pattern here 🫠)
• Errors and warnings are very "Perl-ish", and can be confusing. (translating: good luck decoding those messages, they're giving cryptic 💀)
• Trying to write to a bucket that does not exist or is not accessible by the user generates less than helpful error messages. (so you'll be sitting there like ??? 🙈)
• Trying to put a bucket instead of an item is silently skipped. (no error, no warning, just nothing. ghosted. 👻)

---

🔥 TODO 🔥

the wishlist, the vision board, the "one day" list:

option to read from files instead of stdin
use the fs mtime to set the http Last-Modified
option to read filenames to read from, from stdin
option to read from a tar file stream, for multiple items
option to magically guess mime type
option to use extended file attributes for metadata
option to have a progress bar

a progress bar?? the girlies are asking. the people want the progress bar. 🍓

---

👑 AUTHOR 👑

Written by Mark Atwood mark@fallenpegasus.com.

Many thanks to Wotan LLC <http://wotanllc.com>, for supporting the development of these S3 tools. 🫶

Many thanks to the Amazon AWS engineers for developing S3. absolute icons, respect where respect is due. ⭐

---

🦋 SEE ALSO 🦋

• These tools use the Net::Amazon:S3 Perl module.
• The Amazon Simple Storage Service (S3) is documented at <http://aws.amazon.com/s3>.

---

and that's the whole page bestie!! 💖 this lil gem comes from perl v5.34.0, dated 2022-06-16, filed under S3PUT(1p) in the User Contributed Perl Documentation section. go forth and put some things in S3, and keep those keys confidential, fr fr 🌸✨💅