This is the basic instructions to use file sharing, a feature currently in development.
File sharing can be used in 2 ways: with a component or with a client
- 1 component mode
- 2 client mode
- 3 use with Libervia
- 4 use wich Cagou
- 5 notes
- 6 future
create the component
In this mode you have your file stored on the component which is most of time on the same machine as your server. The component is handled by SàT itself (which is able to do this since 0.7 version).
To create the component, you have to enter the following command:
jp profile create files -p shared_secret -j files.your_domain.tld -C file_sharing
where you obviously change shared_secret and your_domain.tld
- files is the name of the profile of your new component
- files.your_domain.tld is it's jid
- -C file_sharing indicate that you want to create a component and not a normal client. file_sharing is your "component entry point", in other words it's the name of the plugin which will be used as main class.
Once your component is created, you have to add it to your XMPP server, for prosody you do like this:
Component "files.your_domain.tld" component_secret = "shared_secret"
No you can connect your component with:
jp profile connect -cp files
and you're done.
upload a file
Then you send files the same way as you send file to any contact, with a little subtlety (see below)
jp file send your_file.ext files.your_domain.tld -d your_subdirectory
- the file your_file.ext will be sent using jingle to your newly created component
- the new -d your_subdirectory argument indicate where your want to store the file, pretty much like filesystem directories. New directories will be created automatically if needed.
- there is an other new option --namespace (not used in the example), which allows to specify a virtual location to place your file. For instance if you plan to store holiday pictures, you can use "--namespace summer_holidays_2017"
- if you upload an image, a thumbnail is automatically created
Note: it's is not yet possible to delete uploaded files (except by manually doing it on the server). This is of course planed before 0.7 release.
The other files manipulations are the same as for client mode below.
In client mode, you're sharing a local directory (and all its subdirectories, be careful with that).
To do it, it's simple, you can go to your directory to share, and enter following command:
jp file share path -cp louise . -j nestor@your_domain.tld -j pierre@other_domain.tld
- the new file subcommand share handle file sharing.
- share path share a directory and its subdirectories
- -cp louise is, as usual, the profile you want to use, with -c to connect it if it's not the case
- . is the path you want to share. Here we share the current working directory (i.e. the dir where you are). You can enter the path of a single file, in which case it will be put in "files" virtual directory.
- -j nestor@your_domain.tld if an entity jid to add to the whitelist. By default only you (i.e. louise in the example) can access the file (from any device), you have to explicitly add people you want to share the file with. In this example, nestor@your_domain.tld and pierre@other_domain.tld can see the files, other can still ask listing, but files they can't access will not be visible/available.
- instead of -j xxx you can use --public to make the file accessible to everybody
listing files and directories
listing files is as simple as:
jp file share list files.your_domain.tld -v
- share list list files offered by an entity
- files.your_domain.tld is the entity you want to check. Here we use the previously created component. Note that for a client you need to specify the full jid (with the resource), as files are shared per device. For instance it can be louise@your_domain.tld/SàT
- verbosity is used. By default only files/directories names are shown, we use -v to diplay files sizes
- -d (not used in the example) allows to specify the path. For instance you could use -d images/photos/my_photo_album
requesting a file
To request a file, you use:
jp file request -n file_name.ext -d file/path files.your_domain.tld
- file request do a jingle file request
- you then need to specify enough information to retrieve the file. Here we know the filename and its path, so we use -n file_name.ext and -d file/path files.your_domain.tld. We could use the hash of the file, or its namespace (check --help for details)
- by default the file is downloaded in current dir, but you can specify an other one with -D
use with Libervia
With Libervia, you have a graphical interface which should be straightforward to use. You own devices or devices of contacts which implement file sharing should be visible in the "file sharing" menu.
use wich Cagou
Cagou interface for file sharing is similar to Libervia's one.
You can share files or directories on Cagou : go to "file sharing" widget, and select the mode "share local files" to… share local files, or "view shared files" to see and download remote files (from a file sharing service, your own other devices or your contacts devices).
To share a file in "share local files" mode, you just have to do a long touch/click on a file or directory to share, then click on "share" menu, and select contacts you want to share this file/directory with. Click outside contact selection menu to start sharing. If you have selected nobody, only your own devices will have access to this file/directory.
- files are transmitted efficiently using Jingle. For instance if you use file sharing to send files from your mobile phone to your computer on local network, the file will be transmitted on the local network (signalling and negotiation still go through XMPP server though, but it is small size).
- file are for now sent unencrypted. Jingle encryption is planed using OMEMO and/or OX. May land in 0.8
- while using Libervia files are for now downloaded by the server, then sent to the client. This means that downloading is using https for component hosted files (but upload is unencrypted), and server has to download files even for files shared on local network when using Libervia. This should be fixed in 0.8 release with the implementation of WebRTC
- a jp command will use FUSE to allow to mount the shared directory locally.
- file deletion is planed before 0.7 release.
- quotas are planed too