termsend(1)

bofc manual pages

termsend(1)


 

NAME

termsend - share files or program output from command line using the most basic UNIX tools  

SYNOPSIS

termsend [ -h | -v | options ]  

DESCRIPTION

This server has one job - receive files and return link to uploaded content. There are no headers, after client connects every received byte is treated as part of file content and is stored on the server. There is a need for at least one control frame - it's not enough to just close connection after file has been transfered, because then, uploader won't receive link to his uploaded file. Client could of course send FIN with shutdown() function at the end of transfer but not all clients do that - nc, for example, nc does not issue FIN once stdin ends, but socat does that. The only control frame is an ending string - termsend\n. When this string is received at the end of stream, server returns link to uploaded content and closes connection. This simplicity is intentional, as thanks to this, files can be uploaded to the server using the most simple tools from terminal such as netcat and cat. Downloading or displaying files are as easy as calling curl on link that server returns. Both text an binary files can be uploaded to the server, but because there are no control headers, server knows nothing about it and it's up to the user to properly download and process received file. This mode is good for uploading outputs that can stall for long time.

To sumarize, upload will succed when:

- "termsend\n" is seen at the end of transfer
- client sends FIN, which is treated as end of stdin and thus end of upload

Upload will fail when:

- max-timeout passes and neither "termsend\n" nor FIN is seen
- client closes connection without waiting for data and FIN from server.
- client connects and immediately sends FIN (no data sent)
- client connects sends, only "termsend\n" and sends FIN (no data sent)

Timed upload

Normally termsend will wait for "termsend\n" string and if no data is sent within MAX_TIMEOUT seconds connection will be closed with error and data will not be saved. You can however use timed upload to send data without the "termsend\n" string, which will make uploading even easier. If you use timed upload, and timeout occurs, server will save uploaded data and link will be sent back to the client. When "termsend\n" is seen, link will be transmited back immediately as it is done in non-timed upload. When client sends FIN, link will also be send immediately, but for clients that does nothing when stdin ends (netcat), server will wait timeout seconds until link is provided. Because of that, it's advisible to set timed-max-timeout to small value like 3 seconds or so. So since, timeout upload is more versatile than non-upload one, it is not to be used with programs that can output data slowly.

This can be important, for example, when you want to upload output of make. 

    make | nc termsend.pl 1338

In this situation when make does not output anything, which is not something strange when big C++ file with templates is being compiled, server will save partial output and close connection. On the other hand, if you set timeout to big value, client will hand for that time waiting for server to respond.

To sumarize, upload will succed when:

- "termsend\n" is seen at the end of transfer
- client sends FIN, which is treated as end of stdin and thus end of upload
- timed-max-timeout passes and no data is seen during that period

Upload will fail when:

- client closes connection without waiting for data and FIN from server.
- client connects and immediately sends FIN (no data sent)
- client connects sends, only "termsend\n" and sends FIN (no data sent)
- client connects and does not send anything until timeout occurs (no data sent)

If you still don't know which mode to use - if you don't want to support uploading from slow programs, use timed upload as it's more versatile. Otherwise use non-timed with big timeout. And remember you can always start termsend in both modes working on 2 different ports.  

OPTIONS

-h
Prints short help and exits
-v
Prints version number and exits
-l, --level=<level>
Verbosity of logs. level can be one of: 
    0   fatal errors, application cannot continue
    1   major failure, needs immediate attention
    2   critical errors
    3   error but recoverable
    4   warnings
    5   normal message, but of high importance
    6   info log, doesn't print that much (default)
    7   debug, not needed in production
-c
When enabled, ANSI colors will be added to program logs depending on log level. Usefull for spotting errors and warnings, but might not work with all terminals and tools.

Passing 0 as port number will disable given socket.

-i, --listen-port=<port>
Program will listen on specified port for incoming connections. This port will be used for handling unencrypted connections that ends with termsend\n string. When no data in max-timeout is received, connection is closed with error.
Default is: 1337
-a, --timed-listen-port=<port>
Program will listen on specified port for incoming connections. This port will be used for handling unencrypted connections and data does not have to end with termsend\n string. Transfer ends if either termsend\n string is seen at the end or, client issues gentle connection close with shutdown() function or timed-max-timeout passes.
Default is: 1338
-I, --ssl-listen-port=<port>
Program will listen on specified port for incoming connections. This port will be used for handling encrypted connections that ends with termsend\n string. When no data in max-timeout is received, connection is closed with error. For this to work, you will also need to set --key-file and --cert-file.
-A, --timed-ssl-listen-port=<port>
Program will listen on specified port for incoming connections. This works in the same way as timed-listen-port but over encrypted socket. For this to work, you will also need to set --key-file and --cert-file.
-k, --key-file=<path>
When --ssl-listen-port is set, you need to set path to a key file in PEM format.
-C, --cert-file=<path>
When --ssl-listen-port is set, you need to set path to a certificate file in PEM format. Both key and self-signed certificate can be generated via

  
    # create new 2048 bit long RSA key
    openssl genrsa -out termsend.key 2048
    # create self-signed certificate
    openssl req -new -key termsend.key -x509 -days 3650 -out termsend.crt
    # key should be secret and unavailable to outer world
    chmod 600 termsend.key


 
Keep in mind, that users will have to have your termsend.crt file in order to verify your server. Without that, user will not be sure if your server really belongs to you and will be suscible to man-in-the-middle attack.
-f, --pem-pass-file=<path>
If your key is encrypted with password, you can pass path to a file, which contains password for the key. File should contain only password, file should end with new line character, which will be trimmed. If your password ends with a new line character, file should have 2 new line characters at the end of file.
-s, --max-filesize=<size>
Maximum size of file that can be uploaded to server. If uploaded size of file is bigger than configured, user will receive error, and file will not be stored on the server.
Default is: 1048576 bytes (1MiB)
-D, --daemonize
Program will try to run as daemon. If termsend is called as root, program will try to drop priviliges and run with user and group priviliges. If user and group is not set, program will try to run with termsend user and group.
Default is: off
-m, --max-connections=<number>
Defines how many clients can be connected (active uploads) simultaneously. If this number is reached, and new connection is inboud, user will receive information about limit reach and connection will be closed.
Default is: 10
-t, --max-timeout=<seconds>
If during upload, client doesn't send any single bytes for configured seconds, server will close connection and information will be sent back to the client informing him about timeout - as it is possible that he forgot to end upload with special phrase termsend\n.
Default is: 60
-T, --list-type=<type>
When type is set to -1, program operates in blacklist mode. If connected clients ip is in the list_file, such connection will be droped and information to user about his banishment will be sent.
When type is set to 1, program oeprates in whitelist mode. Only clients listed in list_file will be able to upload files. Everyone else will receive access denied error.
When type is set to 0, everyone can upload without restriction.
Default is: 0
-L, --list_file=<path>
Path to list of IPs, which will be filtered base on list-type option. One IP per line is allowed.
Default is: /etc/termsend-iplist
-b, --bind-ip=<ip-list>
Comma separeted list of IPs. Program will listen only on IPs listed in ip-list field.
Default is: 0.0.0.0 (accept connection from any source)
-d, --domain=<domain>
Domain on which server runs. This will be used to send user back information where he can download what he just sent.
Default is: localhost - you definately want to change this.
-u, --user=<user>
user that should run server. Only works when run as daemon started from root account.
Default is: termsend
-g, --group=<group>
group that should run server. Only works when run as daemon started from root account.
Default is: termsend
-q, --query-log=<path>
Place where all queries will be logged. Check FILES section for more information
Default is: /var/log/termsend-query.log
-p, --program-log=<path>
Program log path. Check FILES section for more information.
Default is: /var/log/termsend.log
-P, --pid-file=<path>
Where to store programs pid. Only works if run as daemon.
Default is: /var/run/termsend.pid
-o, --output-dir=<path>
Location where all uploaded files will be stored. Check FILES section for more information.
Default is: /var/lib/termsend
 

FILES

These are default file locations. They can be changed via options.

/etc/termsend/iplist
Separated by new line list of IPs that are filtered (depending on list_type field). One IP per line is allowed
/etc/termsend/termsend.cert
SSL certificate to use with encrypted uploads
/etc/termsend/termsend.key
SSL key to use with encrypted uploads
/var/run/termsend.pid
Process id of working daemon. This file is created only when program is run with -d option
/var/log/termsend-query.log
Every upload query will be logged here exactly once. If query failed, short reason is added and more information about failure can be found in program log. For successful queries, filename is loged. All queries will contain date of upload and source IP.
/var/log/termsend.log
General execution logs are kept here. Detailed information about errornous queries will be here.
/var/lib/termsend
Directory where all uploaded files are stored - usually root of http from where people can download files. User that runs program should have write access to this directory. http server should have read access to this directory.
 

BUG REPORTING

Please report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"

bofc.pl

23 August 2019 (v1.1.1)

termsend(1)