`asfa` - avoid sending file attachments

Since I handle my emails mostly via ssh on a remote server (shoutout to neomutt, OfflineIMAP and msmtp), I needed a quick and easy possibility to attach files to emails. As email attachments are rightfully frowned upon, I did not want to simply copy files over to the remote site to attach them. Furthermore, I often need to share generated files (such as plots or logfiles) on our group-internal mattermost or any other form of text-based communication. Ideally, I want to do this from the folder I am already in on the terminal - and not by to navigating back to it from the browser's "file open" menu…

Therefore, I needed a quick tool that let's me

send a link instead of the file.
support aliases because sometimes plot_with_specific_parameters.svg is more descriptive than plot.svg, especially a few weeks later.
have the link "just work" for non-tech-savvy people, i.e. not have the file be password-protected, but still only accessible for people who possess the link. Here it is helpful to own a domain somewhat resembling your last name.
keep track of which files I shared.
easily clean files by signed index, regex or checksum.
verify that all files uploaded correctly.
do everything from the command line.
have an excuse to to use Rust for something other than Advent of Code.
(have a name that can only be typed with the left hand without moving.)

asfa works by uploading the given file to a publicly reachable location on the remote server via SSH. The link prefix of variable length is then generated from the checksum of the uploaded file. Hence, it is non-guessable (only people with the correct link can access it) and can be used to verify the file uploaded correctly.

The emitted link can then be copied and pasted.

asfa uses a single ssh-connection for each invocation which is convenient if you have confirmations enabled for each ssh-agent usage (see details). Alternatively, private key files in PEM format or openssh-format (i.e., private key starts with -----BEGIN OPENSSH PRIVATE KEY-----) can be used directly.

Usage

Note: All commands can actually be abbreviated: * p for push * l for list * c for clean * v for verify

Push

Push (upload) a local file to the remote site and print the URL under which it is reachable. text $ asfa push my-file.txt https://my-domain.eu/my-uploads/V66lLtli0Ei4hw3tNkCTXOcweBrneNjt/my-very-specific-file.txt See example at the top. Because the file is identified by its hash, uploading the same file twice will generate the same link.

Push with alias

Push a file to the server under a different name. This is useful if you want to share a logfile or plot with a generic name.

Note that if you specify several files to upload with their own aliases, you need to explicity assign the arguments.

Or specify the aliases afterwards. text $ asfa push my-file.txt my-file-2.txt --alias my-very-specific-file.txt my-very-specific-file-2.txt https://my-domain.eu/my-uploads/V66lLtli0Ei4hw3tNkCTXOcweBrneNjt/my-very-specific-file.txt https://my-domain.eu/my-uploads/HiGdwtoXcXotyhDxQxydu4zqKwFQ-9pY/my-very-specific-file-2.txt

Automatically expiring uploaded files

Uploads can be automatically expired after a certain time via --expire <delay>. <delay> can be anything from minutes to hours, days even months. It requires at to be installed and running at the remote site.

List

List all files currently available online:

Detailed list

List all files with meta data via --details:

Clean

Remove the file from remote site via index (negative indices need to be sepearated by --):

You can also ensure that a specific file is deleted by specifying --file:

Note that the file is deleted even though it was uploaded with an alias.

Verify

In case an upload gets canceled early, all files can be checked for validity via verify:

text $ asfa verify ✓ my-very-specific-file.txt ... Verified. ✓ my-very-specific-file-2.txt . Verified.

Since the prefix is the checksum, the check can be performed whether the file exists locally or not.

Filtering by upload date

All commands accept a --newer/--older <n>{min,hour,day,week,month} argument that can be used to narrow down the number of files.

Cleaning all files older than a month can, for example, be achieved via text $ asfa clean --older 1month $ asfa clean --older 1M

All files uploaded within the last five minutes can be listed via text $ asfa list --newer 5min $ asfa list --newer 5m

Requirements

A remote server that * is accessible via ssh * has a webserver running * has writable folder served by your webserver * (optional) has sha2-related hashing tools installed (sha256sum/sha512sum)

Install

Simply install via cargo text $ cargo install asfa

or build from source

text $ git clone https://github.com/obreitwi/asfa.git $ cargo install --path asfa

Configuration

Configuration resides in ~/.config/asfa/config.yaml. Host-specific configuration can also be split into single files residing under ~/.config/asfa/hosts/<alias>.yaml.

System-wide configuration can be placed in /etc/asfa with the same folder structure.

An example config can be found in ./example-config. Here, we assume that your server can be reached at https://my-domain.eu and that the folder /var/wwww/default/my-uploads will be served at https://my-domain.eu/my-uploads.

`asfa`-side

A fully commented example config can be found here.

Minimal: `~/.config/asfa/hosts/my-remote-site.yaml`

yaml hostname: my-hostname.eu folder: /var/www/default/my-uploads url: https://my-domain.eu/my-uploads group: www-data

Full (single-file): `~/.config/asfa/config.yaml`

yaml default_host: my-remote-site prefix_length: 32 verify_via_hash: true auth: interactive: true use_agent: true hosts: my-remote-site: # note: port is optional and defaults to 22 hostname: my-hostname.eu:22 folder: /var/www/default/my-uploads url: https://my-domain.eu/my-uploads group: www-data auth: interactive: false use_agent: true private_key_file: /path/to/private/key/in/pem/format #optional

Webserver

Whatever webserver you are using, you have to make sure the following requirements are met: * The user as which you upload needs to have write access to your configured folder. * Your webserver needs to serve folder at url. * In case you do not want your uploaded data to be world-readable, set group to the group of your webserver. * Make sure your webserver does not serve indexes of folder, otherwise any visitor can see all uploaded files rather easily.

Apache

Your apache config can be as simple as: apache <Directory /var/www/default/my-uploads> Options None allow from all </Directory> Make sure that Options does not contain Indexes, otherwise any visitor could very easily access all uploaded files.

nginx

nginx location /my-uploads { autoindex off }

Background

As a small exercise for writing rust, I ported a small python script I had been using for a couple of years.

For security reasons I have my gpg-agent (acting as ssh-agent) set up to confirm each usage upon connecting to remote servers and the previous hack required three connections (and confirmations) to perform its task. asfa is set up to only use one ssh-connection per invocation.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

asfa - avoid sending file attachments