sshare/README.md

126 lines
3.7 KiB
Markdown

# SSHare
Upload files to a server via ssh
## Documentation
### Arguments
#### `-h` `--help`
Show the help message and exit
#### `-v` `--version`
Show the program's version number and exit
#### `-l` `--latest`
Upload the most recently modified file in `source_directory`
#### `-p` `--paste`
Upload the contents of the clipboard as a `.txt` file
#### `-f FILE` `--file FILE`
Upload a file
#### `-c` `--copy`
Copy the resultant URL to the clipboard
### Configuration File
The configuration file is located at `$XDG_CONFIG_DIR/sshare/config.toml`.
If `XDG_CONFIG_DIR` is not set, then it will read from `$HOME/.config/sshare/config.toml` instead.
#### `source_directory`
The directory from which `--latest` reads.
- [x] Optional - Cannot use `--latest` if it is not set
#### `host`
```
https://example.com:4430/path/to/files/*
^---^ ^---------^ ^--^^------------^
| | | |
| | | +- `host.path` = "/path/to/files"
| | +----- `host.port` = 4430
| +----------------- `host.name` = "example.com"
+------------------------- `host.protocol` = "https"
https://example.com/*
^---------^
|
| `host.path` Not set
| `host.port` Not set
+----------------- `host.name` = "example.com"
`host.protocol` Not set (Defaults to `https`)
```
#### `host.protocol`
The protocol by which the file is served
- [x] Optional - Default: `https`
#### `host.name`
The name of the host (e.g. `example.com`, `1.1.1.1`)
- [ ] Not optional
#### `host.port`
The port from which the host is serving files
- [x] Optional - Default: `None` (which means the default port for the protocol)
#### `host.path`
The subpath from which the host is serving files. If set, `host.path` must start
with and **NOT** end with a `/` (e.g. `/path/to/files` not `path/to/files/`)
- [x] Optional - If the host is serving from the root
#### `ssh`
```
ssh -p 1234 example@example.com:/srv/static
^--^ ^-----^ ^---------^ ^---------^
| | | |
| | | +- `ssh.path` = "/srv/static"
| | +------------- Uses `host.name`
| +--------------------- `ssh.user` = "example"
+-------------------------- `ssh.port` = 1234"
ssh example@example.com:/srv/static
^-----^ ^---------^ ^---------^
| | |
| | +- `ssh.path` = "/srv/static"
| +------------- Uses `host.name`
+--------------------- `ssh.user` Doesn't need to be set if `example` is
the name of the user running `sshare`
`ssh.part` Not set (Defaults to 22)
```
#### `ssh.port`
The port the server is listening for ssh connections on
- [x] Optional - Default: 22
#### `ssh.user`
The user to connect to the host with
- [x] Optional - Default: The user that ran `sshare`
#### `ssh.path`
The directory on the host from which static files are being hosted. If set,
`ssh.path` must **NOT** end with a path (e.g. `/srv/static` not `/srv/static/`)
- [ ] Not optional
#### Example Configuration File
```toml
# config.toml
source_directory = "/home/example/Pictures/Screenshots"
# Host is serving static files at https://example.com:443/sshare/*
# Note: both protocol and port would be optional here as https is
# the default protocol and port 443 is the default https port
[host]
protocol = "https"
name = "example.com"
port = 443
path = "/sshare"
# Host is listening for ssh connections on port 1234 and
# serving files from the `/srv/sshare` directory
[ssh]
port = 1234
user = "exampleuser2"
path = "/srv/sshare"
```