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 helps you with (2) and (3). In the future it may also help you with (4), but for now that step has to be done manually.

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.

b2 [-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 path
The directory to share.
Metadata path
Where to store the metadata. Default: .chifs-share/ in the shared 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 address [flags]

Address and port that the internal web server will listen on. UNIX sockets are supported with the unix:/some/path format. 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.
MaxB2Chunks number
Maximum number of hash chunks to store for a file. Default: 256.
MinB2ChunkSize 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.