ChiFS

Logo pending™

chifs-share(1)

NAME

chifs-share - A command-line Share manager for the ChiFS file sharing network

SYNOPSIS

chifs-share [options] command [args]

chifs-share -V | --version

chifs-share -h | --help

DESCRIPTION

ChiFS is a P2P file sharing network built on top of the Tor anonymity network. chifs-share is a command-line utility that helps you share a particular directory on the ChiFS network. The following components are necessary to publish something on ChiFS:

  1. A directory with files that you wish share,
  2. Metadata generated from that directory,
  3. A web server to publish the files and the metadata,
  4. A Tor Onion Service to make the web server accessible on the network.

chifs-share can help you with everything except (1).

Note that chifs-share follows the UNIX philosophy of not giving any output when everything is working fine. You will typically want to pass -vv to get any useful progress information. A fancy progress bar may be added in the future, though.

GLOBAL OPTIONS

-c, --config FILE
Read configuration from the given file. If this option is not set, the configuration will be read from the CHIFS_SHARE_CONFIG environment variable or $HOME/.chifs-share.conf if that variable is not set.
-v, --verbose
Increase verbosity. Normally only warnings and errors are output, passing -v once will also show informational messages, passing -vv will also show debugging messages, and if you want even more output there's -vvv to display trace messages.
-q, --quiet
Be more quiet. This suppress warnings at -q and errors at -qq.
--log-file none|-|syslog|FILE
Write logs to a file, syslog or stdout (with -). This overrides the LogFile setting in the configuration file.
--log-level off|error|warn|info|debug|trace
Set the log level. This setting has no effect when --log-file is disabled. This overrides the LogLevel setting in the configuration file.
-V, --version
Print version and exit.
-h, --help
Print help and exit.

COMMANDS

index
Scan the shared directory and update metadata.
server
Run the built-in web server. The server will periodically scan the shared directory keep the metadata up-to-date.
clean-meta [FIELD...]

Remove specific file metadata fields. If no fields are provided, any fields that is not mentioned in the Meta setting in the configuration file will be removed from the Share metadata.

This command should be run after removing fields from the Meta setting.

update-meta [-f|--force] [FIELD...]

Populate file metadata fields. If no fields are provided, all fields mentioned in the Meta setting in the configuration file will be populated.

The --force flag will repopulate the metadata fields for all files, even when the files already have said metadata.

This command should be run after adding fields to the Meta setting. Newly scanned files will automatically have all configured metadata fields populated by the index or server commands, so there is no need to manually run update-meta if nothing has changed to the configuration.

b2t [-s SIZE] [-n NUM] FILE

This is a utility command, you likely won't need it often.

Calculates and prints the BLAKE2b root hash of the given file. If the SIZE or NUM arguments are given, then at most NUM intermediate hashes are printed if they are larger than SIZE KiB.

help
Print help and exit.

CONFIGURATION

chifs-share takes a configuration file that describes all aspects of a ChiFS Share. The configuration file follows a similar format to the torrc configuration files as used by tor(1). The following settings are supported:

Share virtual-path filesystem-path

Share a directory at the given virtual path. Virtual paths are visible to the public and can be chosen freely, while the filesystem paths are private and point to the actual file or directory to be shared. This setting can be specified multiple times to share multiple files or directories. It can be thought of as a mount command with the arguments reversed or as an Alias configuration option in the Apache web server. For example:

# The root of our share
Share / /home/user/shared_files

# The filesystem path '/var/www' should be visible at '/www'
Share /www /var/www

# Let's add a 'README.md' file to our public root.
Share /README.md /home/user/share-description.md

To specify a path containing whitespace characters, make sure to quote it, for example:

Share "/Public Files" "/path/to/Public Files"

The internal web server will automatically serve the shared files at the appropriate paths, but when using an external web server you should to make sure that all indicated files and directories are accessible at the paths configured here, for example by using URL rewrites or Alias directives.

Metadata path
Where to store the metadata. Default: .chifs-share/ in the shared root directory. If you are using separate web server (i.e. not the server command built into chifs-share), make sure to configure an alias so that the metadata directory is still reachable at /.chifs-share/
Title text
A descriptive human-readable title for this Share. This will be public. Default: empty.
ContactInfo text
How to contact you. This could be an email address or a URL. This information will be public! Default: empty.
FollowSymlinks yes|no

Enable to publish symlinked files and directories. Default: no.

WARNING#1: This may cause files outside of the Share directory to be shared.

WARNING#2: chifs-share does not currently handle infinite recursion if a symlink points back to a parent directory. Do not enable this option if you do not fully trust the contents of the shared directory!

Ignore pattern

Do not share files that match the given glob pattern. This setting can be provided multiple times to add more ignore patterns.

WARNING#1: While the built-in web server will not share files that match these ignore patterns, the files may still be public if you are using a separate web server.

WARNING#2: Making sure that these pattern match exactly the files that you intend to ignore can take some trial and error. If you have files that you absolutely don't want to be public, it is much safer to keep those out of the Share directory altogether.

Meta field...

Enable the given file metadata fields. This will cause chifs-share to generate and publish the file metadata during the index, server or update-meta commands. It is generally recommended to enable as much useful and metadata as you can, but this may slow down indexing and increase the memory requirements a bit. The following fields are supported:

:ffprobe
Extract metadata from video and audio files using ffprobe(1). Alias for the following fields: album, artist, aspect_ratio, audio, chapters, duration, resolution, subtitles, title, video.
album
Album name, as extracted from the file's ID3/metadata tags using ffprobe(1).
artist
Artist, as extracted from the file's ID3/metadata tags using ffprobe(1).
aspect-ratio
Aspect ratio of video files, extracted using ffprobe(1).
audio
List of audio channels and associated metadata, extracted using ffprobe(1).
chapters
Number of chapters in the media file, extracted using ffprobe(1).
duration
Duration of the media file, extracted using ffprobe(1).
mime
Mime type. This is extracted using the file(1) or mimetype(1) commands.
magic
Description of the file's type, requires the file(1) command.
resolution
Pixel resolution of the media file, extracted using ffprobe(1).
subtitles
List of subtitles embedded in the media file, extracted using ffprobe(1).
title
Title, as extracted from the file's ID3/metadata tags using ffprobe(1).
video
List of video streams and associated metadata, extracted using ffprobe(1).

Multiple Meta settings can be provided in the configuration, this is has same behavior as listing all fields the fields on a single Meta setting. Adding a minus sign ('-') before a field name will exclude that field from the file metadata. For example, to add metadata for all fields provided by ffprobe except for aspect_ratio, the following configuration can be used:

Meta :ffprobe -aspect-ratio

WARNING: In general, file metadata is extracted by reading the shared files and parsing or interpreting their content. This should be relatively safe, but if there are vulnerabilities in the tools used to extract metadata (this is rare, but does happen), then a malicious file in your share could be used to gain access to your system. If you allow untrusted people to add files to your share, it is recommended to sandbox chifs-share to minimize the impact of a potential breach.

LogFile none|-|syslog|FILE
Write logs to a file, syslog or stdout (with -). This can be overridden with the --log-file command line argument. Default: none.
LogLevel off|error|warn|info|debug|trace
Set the log level. This setting has no effect when LogFile is disabled.
Listen tor | address [flags]

Address that the internal web server will listen on. When set to tor, chifs-share will automatically start and configure a private Tor process. This requires the TorDataDir setting to be configured and a tor binary to be available in your $PATH.

When using a separate Tor instance, the web server can be configured to listen on a UNIX socket by giving a unix:/some/path address or to listen to a TCP socket by giving an IP address and port. Default: 127.0.0.1:9080.

For UNIX sockets, the flag GroupWritable or WorldWritable can be given to set the appropriate permissions on the listen socket.

MaxConnections number
Maximum number of simultaneous connections to allow in server mode. Default: 1000.
MaxUploads number
Maximum number of simultaneous uploads. Default: 100.
UpdateInterval n [seconds|minutes|hours|days]
How often the built-in web server will scan the shared directory for changes. Default: 1 hour.
UpdateAtStart yes|no
Scan the shared directory for changes when starting the built-in web server. Default: yes.
TorDataDir path
Path to the directory to be used as private storage for Tor when running in Listen tor mode. The private key for the Onion service are also saved in this directory. The directory will be created it if doesn't exist. This path should not point to a directory that is already being used by another Tor instance!
MaxB2tChunks number
Maximum number of hash chunks to store for a file. Default: 256.
MinB2tChunkSize n [bytes|KB|MB|GB|TB]
Minimum size of a hash chunk. Default: 4MB.

ENVIRONMENT VARIABLES

CHIFS_SHARE_CONFIG
The location of the configuration file to read if the -c option is not given.
RAYON_NUM_THREADS
chifs-share uses rayon to parallelize various operations. This environment variable can be used to control the maximum number of threads to use for parallization. Defaults to the number of detected CPU cores.

SEE ALSO

tor(1)

BUGS

Bugs, feature requests and other issues can be reported to the issue tracker.

Security vulnerabilities should be reported to security@yorhel.nl.