# HG changeset patch # User Goffi # Date 1569962946 -7200 # Node ID 72583524cfd397dd9a0b108dfaf66d5325bbc3d6 # Parent fee60f17ebaceaa2f5fe653ee1f40086d9f8bf5f doc (jp): jp commands are now fully documented: rel 232 diff -r fee60f17ebac -r 72583524cfd3 doc/configuration.rst --- a/doc/configuration.rst Wed Sep 25 08:56:41 2019 +0200 +++ b/doc/configuration.rst Tue Oct 01 22:49:06 2019 +0200 @@ -1,3 +1,5 @@ +.. _configuration: + ============= Configuration ============= diff -r fee60f17ebac -r 72583524cfd3 doc/jp/account.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/account.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,75 @@ +================================ +account: XMPP account management +================================ + +``account`` command help you to create or manage the XMPP account of a server, using +In-Band Registration (`XEP-0077`_). + +.. _XEP-0077: https://xmpp.org/extensions/xep-0077.html + +create +====== + +Create a XMPP account. You have to specify your jid and password as positional arguments. +By default the registration is done on ``localhost`` with default XMPP Client 2 Server +port (i.e. 5222), but you can specify other host/port using ``-H HOST, --host HOST`` and +``-P PORT, --port PORT``. You may also specify an e-mail address using ``-e EMAIL, --email +EMAIL`` (use of this data depend of the server implementation). + +By default, no SàT profile is created and associated to this new XMPP account, but you can +use ``-p PROFILE, --profile PROFILE`` if you are willing to have one. + +example +------- + +Create account for the new user Nestor at ``nestor@example.org`` and associate it with the +SàT profile ``nestor``:: + + $ jp account create nestor@example.org some_password -p nestor + + +modify +====== + +Modify an existing XMPP account password. This will modify the XMPP account linked to the +given profile. + +.. note:: + + Only the XMPP password on the server is changed, not the one registered in the + parameter of SàT. You may have to update the parameter of your profile if the new + password doesn't correspond to your parameters one (you can do that with jp param set + or with most SàT frontends in parameters). + +example +------- + +Change the XMPP password of the XMPP account of the default profile:: + + $ jp account modify new_password + + +delete +====== + +Delete the XMPP account linked to the given profile from the XMPP server. Before using +this command, please be sure to understand well that **THIS WILL REMOVE THE WHOLE XMPP +ACCOUNT AND DATA FROM THE XMPP SERVER**. + +By default a confirmation is requested, you can do this without confirmation by using +``-f, --force``, however this is **NOT RECOMMENDED**, be sure to understand what you're +doing if you use this option (and be sure to spell correctly the profile, if you forget +the ``-p PROFILE, --profile`` argument for instance, this would delete entirely the +default profile). + +.. note:: + + Be extra careful with this command, as it will remove the whole account from the + server, and the associated data. + +example +------- + +Delete the XMPP account of Pierre, which is not on the local server anymore:: + + $ jp account delete -p pierre diff -r fee60f17ebac -r 72583524cfd3 doc/jp/ad-hoc.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/ad-hoc.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,120 @@ +======================= +ad-hoc: Ad-Hoc commands +======================= + +Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used +either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get +list of connected users, send a service announcement, restart parts of the server), or +execute about anything (e.g. control a physical robot with XMPP). + +run +=== + +Run an ad-hoc command. You may specify the node to run as positional argument, or let it +empty to list available commands. + +By default the commands from your server are used, but with ``-j JID, --jid JID`` you can +specify a different entity. + +You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and +``-S, --submit`` as many time as needed. ``--field`` expect a ``KEY`` which is the name +of the field to set. If you don't know which name to use, you can run the command to +automatise a first time manually with ``--verbose, -v`` flag, this will display fields +names when you have to fill them. + +Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then +if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and +so on as many times as you need. + +Don't forget that you can use your shell substitution capabilities if necessary, for +instance if you have a pre-registered announce to send. + +examples +-------- + +Get a list of available commands on your server to launch a command:: + + $ jp ad-hoc run + +If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements +to online users. This can be useful to notify an imminent maintenance of the server. Here +we notify online users that the server will be shutdown in 30 min, using a shell +substitution capabilities with a pre-registered message in the file +``~/announces/maintenance_30.txt``, then we submit it:: + + $ jp ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S + +Get your server uptime (if supported by your server):: + + $ jp ad-hoc run uptime + +Run the commands available at the service with the jid ``someservice.example.org``:: + + $ jp ad-hoc run -s someservice.example.org + +Run you server commands with verbosity so you get the name of the fields that you can fill +automatically later:: + + $ jp ad-hoc run -v + +.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html + +list +==== + +List ad-hoc commands available at a service. + +examples +-------- + +List ad-hoc commands available at your server:: + + $ jp ad-hoc list + +List ad-hoc commands available at a chat service:: + + $ jp ad-hoc list -j conference.example.org + +remote +====== + +Create a remote control from launched media players. Ad-hoc commands to control the media +player will be added to your device, allowing anybody allowed (including yourself from an +other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc. + +To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can +specify who is allowed to control this media player with the following options: + +``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]`` + jids of entities allowed to control the media player + +``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]`` + groups (from your roster) allowed to control you remote + +``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]`` + groups (from your roster) which are **NOT** allowed to control your media player + +``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]`` + jids of entities which are **NOT** allowed to control your media player + +If you want the commands to run repeatedly (in opposition of stopping after first action +is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it. + +.. note:: + + SàT already creates automatically a remote control if it finds a media player. This + manual way to create a remote control predate the automatic remote control, and is + currently more flexible in that you can specify who can access the remote control + (automatic remote control is only accessible by the jid of the profile). + +examples +-------- + +Create a remote control for a running VLC instance:: + + $ jp ad-hoc remote vlc -l + +Create a remote control for a running SMPlayer instance, and allowing anybody from your +``housemates`` group to use it:: + + $ jp ad-hoc remote smplayer -g housemates -l diff -r fee60f17ebac -r 72583524cfd3 doc/jp/avatar.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/avatar.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,44 @@ +=============================== +avatar: retrieve/upload avatars +=============================== + +Avatars are images associated to an XMPP entity. Several XMPP extensions are in use, SàT +tries to hide the technical details so avatar are as easy as possible to manipulate for +end-user. + +get +=== + +Retrieve the avatar of the given entity. Entity jid is specified as positional argument. + +If an avatar is found, a path to its cached file is printed. Please note that this is the +cache used by all SàT ecosystem, **do not modify the cached image**. You may use it for +read-only access, or copy it if you want to modify the image. + +You may use the ``-s, --show`` argument to display the found avatar. The software used to +display the image can be specified in SàT configuration (cf. :ref:`configuration`), in the +``[jp]`` section: the ``image_cmd`` setting let you specify the path to the software. If +``image_cmd`` is not used, ``jp`` will try some common software, and if none is found, it +will try to open the image in a browser (which may sometimes result in using the default +image software of the platform). + +example +------- + +Get the avatar of ``louise@example.org`` and display it:: + + $ jp avatar get --show louise@example.org + + +set +=== + +Upload and set the given avatar for the profile. The only required argument is the path to +the image to use as avatar. + +example +------- + +Set the avatar of the default profile:: + + $ jp avatar set ~/photos/some_photo.jpg diff -r fee60f17ebac -r 72583524cfd3 doc/jp/blog.rst --- a/doc/jp/blog.rst Wed Sep 25 08:56:41 2019 +0200 +++ b/doc/jp/blog.rst Tue Oct 01 22:49:06 2019 +0200 @@ -59,6 +59,8 @@ $ jp blog get -m 2 -O template --oo browser +.. _jp-blog_edit: + edit ==== @@ -255,6 +257,8 @@ $ jp blog preview ~/local/sat/blog/some_name/blog_something.md +.. _jp-blog_import: + import ====== diff -r fee60f17ebac -r 72583524cfd3 doc/jp/bookmarks.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/bookmarks.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,98 @@ +============================ +bookmarks: get/set bookmarks +============================ + +Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons, +XMPP has several ways to handle bookmarks, and SàT handle them as transparently as +possible. + +With SàT there are 3 places where you can get/store your bookmarks: + +local + the bookmarks is stored only locally in the database of SàT. It won't be available to + other devices. +private + the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to + use this if PubSub storage is available +pubsub + the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to + store bookmarks. + +When possible, you can specify ``auto`` to let SàT choose the best location (i.e. +``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible). + +.. _XEP-0049: https://xmpp.org/extensions/xep-0049.html +.. _XEP-0223: https://xmpp.org/extensions/xep-0223.html + + +list +==== + +Get and print available bookmarks. You specify the location of the bookmarks to print +using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default +all bookmarks from all locations are printed. + +Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or +URLs. + +After printing the bookmarks location, the bookmarks will show the name and location (jid +for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if +autojoin is set. + + +examples +-------- + +Retrieve all MUC bookmarks:: + + $ jp bookmarks list + +Retrieve all bookmarked URL stored in PubSub:: + + $ jp bookmarks list -l pubsub -t url + + +remove +====== + +Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as +positional argument. If you are deleting an URL, you need to specify it with ``-t url`` + +By default a confirmation is requested, use ``-f, --force`` if you don't want it (with +usual caution). + +examples +-------- + +Delete the bookmark of a MUC room that you are not following anymore:: + + $ jp bookmarks remove some_old_room@conference.example.net + +Delete the bookmark of a URL without requesting confirmation:: + + $ jp bookmarks remove -t url https://unused_url.example.net + + +add +=== + +Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as +positional argument. If you are bookmarking an URL, you need to specify it with ``-t +url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it. + +For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``, +and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically +when you're connecting. + +If you're using add on a jid/URL which already exists, the metadata will be updated. + +examples +-------- + +Add a bookmark to Salut à Toi official chat room:: + + $ jp bookmarks add sat@chat.jabberfr.org -a + +Add a link to Salut à Toi official website:: + + $ jp bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel" diff -r fee60f17ebac -r 72583524cfd3 doc/jp/common_arguments.rst --- a/doc/jp/common_arguments.rst Wed Sep 25 08:56:41 2019 +0200 +++ b/doc/jp/common_arguments.rst Tue Oct 01 22:49:06 2019 +0200 @@ -4,6 +4,8 @@ Some arguments are used in many commands. This page describe them. +.. _jp-common_profile: + profile ======= @@ -156,6 +158,8 @@ Add a verbosity level (can be used multiple times). Use to have more concise output by default when it makes sense. +.. _draft_common: + draft ===== diff -r fee60f17ebac -r 72583524cfd3 doc/jp/debug.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/debug.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,79 @@ +===================================================== +debug: tools to help debugging/monitoring Salut à Toi +===================================================== + +``debug`` groups commands to monitor or manipulate SàT and XMPP stream. + +.. _jp-debug_bridge_method: + +bridge method +============= + +Call a method of the bridge. You have to provide the name of the method and the arguments +as positional arguments. Arguments are evaluated as Python code (using ``eval``), so you +need to properly escape them (for your shell **and** Python). You can either split your +Python arguments as many shell arguments, or put them in a single shell argument. + +You profile is automatically set if the method requires it (using the value of ``-p +PROFILE, --profile PROFILE``), so you must not specify it as an extra argument. + +You can refer to `Bridge API documentation`_ to get core methods signatures + +.. _Bridge API documentation: https://wiki.goffi.org/wiki/Bridge_API + + +examples +-------- + +Send a message using a single shell arguments for all Python arguments. We +use first the method name (``messageSend``), then the required arguments (see `Bridge +API documentation`_ for details), without the profile as it is automatically set. We +specify them as Python in one shell argument, so we use single quote (``\```)first for +s hell string, and inside it we use double quote (``"``) for Python strings:: + + $ jp debug bridge method messageSend '"louise@example.org", {"": "test message"}, {}, "auto", {}' + +.. note:: + + This is for debugging only, if you want to send message with jp, use :ref:`jp-message_send`. + +Get version string of SàT:: + + $ jp debug bridge method getVersion + + +bridge signal +============= + +Send a fake signal. This is specially useful to test behaviour of a frontend when a +specific event happens. To use is you just need to specify the name of the signal and the +arguments to use (using Python eval in the same way as for jp-debug_bridge_method_). + +example +------- + +Send a note with ``info`` level and hand written XMLUI. Here me use a shell variable to +store the level, so we can easily change it if we want to use an other level for tests. +Note the use of quotes (to escape both for shell and Python):: + + $ LEVEL='info'; jp debug bridge signal -c actionNew '{"xmlui": '"'"'test message\non\nseveral\nlines'"'"'}' '""' -1 + + +monitor +======= + +Show raw XML stream. By default, output is pretty formatted/highlighted and you get all +streams in both direction. You can filter the direction using ``-d {in,out,both}, +--direction {in,out,both}``. + +For this to work, you need to set the option ``Activate XML log`` in the ``Debug`` section +of your parameters. + +Verbosity is used, to print details on the direction of a stanza, use ``--verbose, -v`` + +example +------- + +Monitor raw XML stream:: + + $ jp debug monitor -v diff -r fee60f17ebac -r 72583524cfd3 doc/jp/encryption.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/encryption.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,126 @@ +======================================== +encryption: encryption sessions handling +======================================== + +Salut à Toi being an XMPP client does encryption by default between client and server. In +addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the +payload of messages are encrypted to be hidden from the servers (and their +administrators). The ``encryption`` commands are here to handle those e2e encryption +sessions and algorithms. + +.. note:: + + For the moment, only one 2 one chat messages can be e2e encrypted + +algorithms +========== + +Display e2e encryption algorithms available in this instance of Salut à Toi. + +example +------- + +Show available e2e algorithms:: + + $ jp encryption algorithms + +get +=== + +Display which encryption session is currently active with the given entity. + +The only required argument is the JID of the entity. + +If not e2e encryption session exist, a message will be displayed and jp will exit with a +non zero code: this means that the messages are in clear in the XMPP servers, but normal +XMPP encryption is not affected (message should still be encrypted between client and +server and between servers). + +If an e2e encryption session exist, you'll see the algorithm name and its namespace. In +case of e2e encryption which only works from device to device (e.g. it's the case with +``OTR`` which doesn't support multiple devices), you'll also see the resources of the +devices where the encryption is active in ``directed_devices`` + +example +------- + +Check if session is encrypted with Louise:: + + $ jp encryption get louise@example.org + +start +===== + +Start e2e session with an entity. + +You need to specify the JID of the entity you want to start a session with as a positional +argument. + +By default, SàT will select itself the algorithm to use among those available, but you can +specify one using either its name with ``-n NAME, --name NAME`` or its namespace using +``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo`` +while the namespace is the longer (e.g. ``urn:xmpp:otr:0``). + +If an encryption session is started but one with an other algorithm was already there, the +original session will be stopped and replaced by one with the new requested algorithm. You +can change this behaviour by using ``--encrypt-noreplace``: in this case the command will +fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e +encryption session was already started with an other algorithm), and return a non-zero +code. If an e2e encryption session was already started with the requested algorithm, the +command will succeed in all cases an nothing will be changed. + +examples +-------- + +Start e2e encryption with Pierre, using the algorithm selected by SàT:: + + $ jp encryption start louise@example.net + +Start an OMEMO session with Louise:: + + $ jp encryption start -n omemo louise@example.org + +stop +==== + +Terminate an e2e session with given entity. The entity must be specified as positional +argument. + +After this command is run, the messages with specified entity will not be e2e encrypted +anymore (but this won't affect encryption between SàT and XMPP server and between XMPP +servers). + +example +------- + +Stop the e2e encryption session with Pierre:: + + $ jp encryption stop pierre@example.net + +trust ui +======== + +Run the user interface to handle trust with given entity and given algorithm. The user +interface depends of the algorithm used, but it generally shows you the fingerprints +associated with your contact or contact devices, and asks you if you trust them or not. + +The only mandatory argument is the jid of your contact. + +By default the currently active encryption session algorithm is used, but you may manage +trust for an other algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE, +--namespace NAMESPACE``. + +.. note:: + + Trusting a contact or a device means that you certify that this contact or device is + the one you want to talk too. You should not trust a device if you have not verified by + an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the + fingerprint physically if possible (i.e. in front of your contact, not with computer + networks in the middle). + +example +------- + +Manage ``OMEMO`` trust with Louise devices:: + + $ jp encryption trust ui -n omemo louise@example.org diff -r fee60f17ebac -r 72583524cfd3 doc/jp/event.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/event.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,69 @@ +======================== +event: events management +======================== + +Event commands allows you to create/modify or get data about an event, and to manage your +invitees. + +.. _jp-event_get: + +get +=== + +Get metadata about a specific event. + +example +------- + +Retrieve an event metadata:: + + $ jp event get -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0' + +.. _jp-event_create: + +create +====== + +Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``, +and an id with ``-i ID, --id ID`` (default id is used if omitted). + +Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key +can be a custom data or one of: + +name + name of the event +description + details of the event +image + URL of the main picture of the event +background-image + URL of image to use as background +register + a boolean value, set to ``true`` if you want to register the event in your local list + +example +------- + +Create an event about to celebrate New Year:: + + $ jp event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg + + +modify +====== + +This command in the same way as jp-event_create_ but modify an existing event. You need to +specify the node of the event to modify using ``-n NODE, --node NODE``. + +example +------- + +Add a background image to the New Year event created above:: + + $ jp event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg + + +invitee +======= + +Subcommands to handle guests. Please check :ref:`jp-event_invitee`. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/event_invitee.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/event_invitee.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,94 @@ +.. _jp-event_invitee: + +======================================== +event/invitee: event invitees management +======================================== + +``invitee`` groups commands to invite somebody to an event, get or set data about an invitee, and list all invitees. You can send an invitation by e-mail to people without XMPP account. + +.. _jp-event_invitee_get: + +get +=== + +Retrieve the RSVP status of one guest. Note that you must the invitees node and not the +event node. To retrieve invitees node, use :ref:`jp-event_get` with the event node. + +You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare +jid will be used). + +If no response is known yet, no data is returned. + +example +------- + +Get RSVP of Louise:: + + $ jp event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org + + +.. _jp-event_invitee_set: + +set +=== + +Set your own RSVP data. Note that as for jp-event_invitee_get_ you must use +invitees node and not the event node. + +Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of +``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value +must be an integer. + +example +------- + +Indicate that you'll come to an event with 3 guests:: + + $ jp event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3 + +list +==== + +Get and format the RSVP of your invitees. Note that as for jp-event_invitee_get_ and +jp-event_invitee_set_ you must use invitees node and not the event node. + +By default, only people who have answered are shown. You may use ``-m, --missing`` to show +other people which were invited, but have not answered yet. When using this option, you +can also use ``-R, --no-rsvp`` to only show people which have not answered yet. + +You'll also have a small summary indicating how many people who can expect at your event. + +example +------- + +Get the full list of invitees (including those who didn't answered yet) with the RSVP formatted:: + + $ jp event invitee list -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -m + +invite +------ + +Invite somebody to an event. The invitation is done by e-mail, a guest account will be +created. Contrary to other ``invitee`` commands, in this one you'll use the event node +directly. + +This command is really similar to :ref:`jp-invitation_create` + +E-mail address is specified using ``-e EMAIL, --email EMAIL`` and you'll need to give an +URL template (using ``-U URL_TEMPLATE, --url-template URL_TEMPLATE``)leading to your +website page handling the invitation (for Libervia default invitation page is +``/g/``). You can use ``{uuid}`` as a placeholder which will be +replaced by event's id. + +You'll probably want to specify the name of the invitee, using ``-N NAME, --name NAME`` +and your own name (as the host inviting), using ``-H HOST_NAME, --host-name HOST_NAME``. +The language spoken by your guest can be specified using ``-l LANG, --lang LANG``, it is +mainly useful if you have many invitee speaking different languages. + +example +------- + +Pierre is inviting Louise (whose e-mail address is ``louise_email@example.net``) to an +event he's organising:: + + $ jp event invitee invite -e louise_email@example.et -N "Louise" -H "Pierre" -l fr -U "https://www.example.org/g/{uuid}" -u "xmpp:pierre@example.org?;node=generic%2F61400ea7-a2a2-4ce0-9b68-3735b602f671" diff -r fee60f17ebac -r 72583524cfd3 doc/jp/file.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/file.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,147 @@ +======================================== +file: files sending/receiving/management +======================================== + +``file`` group all commands related to file management, and allows you to send easily a +file to a contact or device from the command line. + +send +==== + +Send a file to a contact. + +The file will be sent using best available method (which is Jingle File Transfer when +available), and will try to send the file in P2P when possible. If P2P is possible, the +signal is sent through the server (metadata, negotiation, etc.), while the file itself +goes directly from the source device to the target device. When P2P is not possible, the +file may go through the server or an other one (if a proxy is used for instance). + +When sending a file, you specify one or more file(s) to send, and the either the bare jid +or the full jid of the target device. If bare jid is specified, the main resource will be +used. + +You'll usually want to see the progression of the transfer, use ``-P, --progress`` for +that. + +If you send several files at once, you may want to use ``-b, --bz2`` to group them in a +single compressed ``tar.bz2`` archive (the client receiving the files will then receive a +single file, than the user can then decompress). + +By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to +specify another one. + +The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace +NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like +a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group +of files, for instance for a photo album). + +examples +-------- + +Send a file to Louise, with a progress bar:: + + $ jp file send -P some_file.ext louise@example.org + +Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in +the ``/some/path`` path:: + + $ jp file send -P -N holidays -d /some/path some_photo.jpg files.example.org + +.. _jp-file_request: + +request +======= + +Ask to get a file from a device/sharing service. A file is requested using one or more +metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H +HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo +HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N +NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific +and not (yet?) XMPP standards. + +If you already know the hash, it's the most efficient and recommended way to retrieve a +file. + +You need to specify the full jid of the device or the sharing service as a positional +argument. + +By default the file is downloaded in current directory, but you can specify an other one +(and an other filename) with ``-D DEST, --dest DEST``. + +If you want to see progression of the transfer, use ``-P, --progress``. + +examples +-------- + +Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service +``files.example.org``, with a progress bar:: + + $ jp file request -P -d photos/demo_album -n some_file.jpg files.example.org + +Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't +specify it), and save it to file ``dest_file.txt``:: + + $ jp file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org + +receive +======= + +Wait for a file (or several ones) to be received, and accept it if it match criteria. + +You should specify which jid you are expecting a file from, using the positional +arguments. If you don't, all files will be accepted, which can be dangerous if some +malicious user send you a file at this moment. + +To see progression (this is recommended), you can use the ``-P, --progress`` options. + +By default, if a file with the same name as the proposed one exists, the transfer will be +denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely +trust the sender in this case, as the name is chosen by her, and could be malicious, or it +could override an important file. + +If you expect several files, you can use the ``-m, --multiple``, in this case the command +won't stop after the file received file, and you'll have to manually stop it with +``Ctrl-C`` or by sending a ``SIGTERM``. + +File(s) will be written in the current directory, but you may specify an other destination +with ``--path DIR``. + +examples +-------- + +Accept and receive the next file, save it to local directory and show a progress bar:: + + $ jp file receive --progress + +Several files are expected from Louise, accept them and store them do +``~/Downloads/Louise``:: + + $ jp file receive --multiple --path ~/Downloads/Louise louise@example.org + + +upload +====== + +Upload a file to your XMPP server (or an other entity if specified). The upload will be +done using `XEP-0363 (HTTP File Upload)`_, and the public URL to retrieve the file will be +printed. Note that anybody knowing this URL can download the file you've uploaded. + +The path to the file to upload is expected as first argument, then optionally the entity +of the service to upload too (by default, this is autodetected if your server offers this +feature). + +As usual, you can use ``-P, --progress`` to see a progress bar. + +.. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload + +example +------- + +Upload a document to a server:: + + $ jp file upload -P ~/Documents/something_interesting.odt + +share +===== + +Subcommands for advanced file sharing. Please check :ref:`jp-file_share`. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/file_share.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/file_share.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,98 @@ +.. _jp-file_share: + +================================== +file/share: advances files sharing +================================== + +``share`` groups commands for listing file available on a device/service, sharing a file +or directory, and inviting people to retrieve files. + +.. _jp-file_share_list: + +list +==== + +List files available on a device or sharing service. You mainly have to specify the jid of +the device/service where the files are stored (if jid is omitted, your own jid will be +used, so you can check what you are sharing). + +.. note:: + + you have to use the full jid of the device if you want to list files available on a + device. + +You may specify a path using ``-d PATH, --path PATH``. + +File and directories are printed with a different colour if you use default output. + +examples +-------- + +List files shared from a device (note that we use a full jid here):: + + $ jp file share list louise@example.org/some_resource + +List files available on a sharing service at the path ``/photos``:: + + $ jp file share list -d photos files.example.org + +Louise wants to list the file shared by Pierre:: + + $ jp file share list pierre@files.example.org + +path +==== + +Share a local file or directory with a list of entities, or publicly. The files can then +be listed or requested using jp-file_share_list_ or :ref:`jp-file_request`. + +You specify the file or directory the positional ``path`` argument. By default the name of +the file/directory is used, but you can give a different one using ``-n NAME, --name +NAME``. + +You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many +time as necessary. If you don't specify any entity, the file will only be accessible by +your own devices. If you want to make your file accessible to everybody, use ``--public`` +(note that this means that your file is accessible to the world, i.e. also to people you +don't know, so use this option carefully). + +examples +-------- + +Share the file ``interesting_doc.odt`` with Pierre and Louise:: + + $ jp file share path -j pierre@example.net -j louise@example.org interesting_doc.odt + +Imagine that you have built a weather station and want to make its data public. You can +share the directory ``~/weather_station_data`` with the world, using the name ``public +weather data``:: + + $ jp file share path --public --name "public weather data" ~/weather_station_data + +invite +====== + +This command send an invitation for a file sharing repository to an XMPP entity. + +The invitation is a non standard (yet?) way to notify somebody of the existence of a files +repository. + +Beside the positional arguments ``service`` and ``jid``, which are respectively the +service where is the files repository and the jid of the entity to invite, you mainly have +to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and +``N NAMESPACE, --namespace NAMESPACE``. + +Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a +generic files repository or a photo album. + +Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL, +--thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of +the album in e.g. Libervia. + +example +------- + +Pierre wants to invite Louise to view his ``summer holidays`` photo album:: + + $ jp file share invite -P "photos/summer holidays" -t photos pierre@files.example.net + louise@example.org diff -r fee60f17ebac -r 72583524cfd3 doc/jp/forums.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/forums.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,102 @@ +============================== +forums: forums topics handling +============================== + +Forums are internally a way to organise blog nodes open to many publishers. The ``forums`` +commands let you manage the structure of topics. You may have several different structures +in one PubSub forums node, this can be useful if you have multi-lingual forums. + +.. _jp-forums_get: + +get +=== + +Get and print the structure of forums. Beside the classic PubSub node arguments, you may +specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have +several structures of forums, for instance one per language. + +If you use the default output, the verbosity is used to retrieve details of topics. + +examples +-------- + +Get structure of default forum with details:: + + $ jp forums get -v + +Get structure of French forums in JSON:: + + $ jp forums get -k fr -O json + + +edit +==== + +Edit the structure of XMPP forums. As for jp-forums_get_ you may specify the key beside +the classic PubSub node arguments. The edition works the same as for :ref:`jp-blog_edit`. + +To edit the structure you'll get a JSON file which is a list of object where the topic +metadata are set. You can use the following metadata: + +``main-language`` + a language code, using `ISO 639`_ +``name`` + short name of the forum +``title`` + title of the topic/category in the given language +``short-desc`` + small description of the topic/category +``desc`` + long description of the topic/category +``uri`` + URI to the PubSub node containing the messages of the topic (it's actually a blog node + with suitable permissions). URI must only be set for topic, not for categories. +``sub-forums`` + list of object with the same metadata (i.e. other topics or categories) + +Here is a small example of a forum structure: + +.. sourcecode:: json + + [ + { + "main-language": "en", + "name": "short-name", + "title": "This is a category", + "short-desc": "short description about the category", + "desc": "this is a an example of a long description" + "sub-forums": [ + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "some intereting topic", + "short-desc": "This is a description explaining what the topic is about" + }, + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "a second topic", + "short-desc": "This topic is about bla bla bla" + }, + ], + }, + { + "main-language": "en", + "title": "An other category", + "sub-forums": [ + { + "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf", + "title": "yet another topic", + "short-desc": "This is a demo topic, made for an example" + }, + ] + } + ] + + +.. _ISO 639: https://www.iso.org/iso-639-language-codes.html + +example +------- + +Edit structure of forums on a PubSub service:: + + $ jp forums edit -s pubsub.example.org diff -r fee60f17ebac -r 72583524cfd3 doc/jp/identity.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/identity.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,34 @@ +============================= +identity: identity management +============================= + +Identity use several XMPP extensions (like vcards) to retrieve or set informations about +an entity. For now it's really basic and only nickname and avatar are managed. + +get +=== + +Retrieve informations about the identity behind an XMPP entity. You only have to specify +the jid of the entity, and you'll get (if set) his/her/its nickname and a link to the +cached avatar. + +example +-------- + +Get identity information about an entity:: + + $ jp identity get somebody@example.org + +set +=== + +Set identity data to the server, using various XMPP extensions. You set the data to change +using ``-f KEY VALUE, --field KEY VALUE``, where ``KEY`` can only be ``nick`` at the +moment. + +example +------- + +Set the nickname of default profile:: + + $ jp identity set -f nick toto diff -r fee60f17ebac -r 72583524cfd3 doc/jp/info.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/info.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,58 @@ + +================================== +info: retrieve various information +================================== + +``info`` groups subcommands used to retrieve read-only informations. + +disco +===== + +Display discovery information (see `XEP-0030`_ for details). This can be used to check +which features you server or a service is offering, and which items are available (items +can be services like chat room, gateways, etc). + +You only have to specify the jid of the entity to check, and optionally a node. + +By default both infos and items are requested, but you can restrict what to request by +using ``-t {infos,items,both}, --type {infos,items,both}`` + +.. _XEP-0030: https://xmpp.org/extensions/xep-0030.html + + +example +------- + +Request infos and items from a server:: + + $ jp info disco example.org + +version +======= + +Request software version of an entity. You only need to specify the jid of the entity as +positional argument. + +Depending of the software and its configuration, you have software version, software name, +and the operating system on which the software is running. + +example +------- + +Check version of a server:: + + $ jp info version example.org + +session +------- + +Give information about the session of the given profile. You'll the full jid currently +used on the server, and the time when the session was started (which may not be the same +time as when the connection with the XMPP server was started). + +example +------- + +Get session informations:: + + $ jp info session diff -r fee60f17ebac -r 72583524cfd3 doc/jp/input.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/input.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,119 @@ +================================================ +input: automatise commands using external inputs +================================================ + +``input`` is a way to use external data (like file in a specific format) as input +arguments. It may be seen as a something similar to ``--output`` but for inputs. + + +csv +=== + +CSV (for Comma-Separated Values) is a common format for tabular data. It is widely used in +spreadsheet software (at least at en export format). With ``csv`` command, you can use +columns a CSV file as arguments to jp commands. + +To set the command, you'll write in sequence what to do with each column of your data. +For each column you can: + +- specify a short option name using ``-s ARGUMENTS, --short ARGUMENTS`` (short options are + the ones with a single ``-``) +- specify a long option name using ``-l ARGUMENTS, --long ARGUMENTS`` (long options are + the ones with two ``-``) +- specify a positional argument using ``-p ARGUMENTS, --positional ARGUMENTS`` +- indicate to use the column data with ``stdin`` using ``-i, --stdin`` +- ignore the column if it's not used in the jp command, using ``-x, --ignore`` + +After each column specification, you may use a filter to manage the value. So far the +following filters are available: + +``-S, --split`` + This will split the value (on any whitespace character, discarding empty values) and + repeat the option which each item. This is useful when you are using an option which can + be repeated (like ``-t TAG, --tag TAG`` with ``jp blog set``). + +``-E ARGUMENTS, --empty ARGUMENTS`` + Indicate what to do if the column value is empty (by default en empty string is used). + You can use either ``skip`` to skip the whole row, or ``ignore`` so the option will not + be set at all (which is different from the default which will still set the option but + with an empty string). + +CSV file is read from stdin, and by default unicode is expected. You may force an encoding +by using ``--encoding ENCODING``. + +By default all the rows are read, but you may want to ignore first rows (if they are used +for columns title, or if you have already handled part of the list). To do that, use the +``-r ROW, --row ROW`` option. + +When you test your command, it is better to do a dry run to see what will happen. The +``-D, --debug`` option is here for that: if you set it, the commands won't be actually +run, but the exact command which would be executed will be printed on screen. You should +always use this option first until you're sure that what you want will be executed. + +You may add verbosity level to help debugging. With a verbosity level of 2 (i.e. ``-vv``) +the value read from CSV will be printed. + +By default stdout and stderr of each launched command is ignored, but you can log them to +files using respectively ``--log LOG`` and ``--log-err LOG_ERR`` where ``LOG`` and +``LOG_ERR`` are paths to a log file to create. + +Once all the sequence and options are set, you write the jp command that you want to use, +with all the needed static option (i.e. options which must be used each time). + + +example +------- + +Louise as a spreadsheet with a table like this: + +============================ ============ ============= =============== +title body internal data tags +============================ ============ ============= =============== +Some title a body ABC jp demo +Something else another body XYZ jp demo +Third one third body VWZ special_tag jp +This one doesn't have a body 123 jp demo numbers +last one last body 456 jp demo numbers +============================ ============ ============= =============== + +She wants to use it as input data to create blog posts. + +She first saves the file using CSV format, let's say to ``~/blog_input.csv``. + +Then she checks ``jp blog set --help`` to get name of options to use. She'll need to use +``--title`` for title, ``stdin`` for the body and ``-t`` for tags. Louise wants to +activate comments, so she also wants to use ``-C`` for all posts, and a tag to says it's +coming from the spreadsheet (using ``-t spreadsheet``) . + +The first row of the table is used for columns headers, so she'll start at row 1 with ``-r +1``. + +There is one row without body, Louise want to skip any row without body so she'll use the +``-E skip`` filter, just after specifying the body row. + +Reading column by column, the sequence is like this: + +``-l title`` + a title which goes to the ``--title`` long option of ``jp blog`` +``-i -E skip`` + a body which goes to the stdin of ``jp blog``. If the body is empty, the ``-E skip`` + filter tells to skip the whole row. +``-x`` + the ``internal data`` column is not used, so it is ignored +``-s t -S`` + the last column are the tags, so the ``-t`` short option is used. There are several of + them separated by spaces, so the ``-S`` filter is used to split the values. + +First she'll use the ``-D, --debug`` to check that the commands which will be executed are +the expected one:: + + $ jp input csv -D -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv + +Everything seems fine, so she'll actually launch the command by running the same command +line but without the ``-D`` option:: + + $ jp input csv -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv + +She could also have used ``--log`` and ``--log-err`` to check the logs of each command:: + + $ jp input csv -r 1 -l title -i -E skip -x -s t -S --log /tmp/jp_blog_stdout.log --log-err /tmp/jp_blog_stderr.log blog set -C -t spreadsheet < ~/blog_input.csv diff -r fee60f17ebac -r 72583524cfd3 doc/jp/invitation.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/invitation.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,96 @@ +============================================== +invitation: invite people without XMPP account +============================================== + +Invitations allows you to invite people without XMPP account, so they can participate e.g. +to a discussion by using a specially generated link. This is a Salut à Toi specific +feature and those commands are rather low lever. + +.. _jp-invitation_create: + +create +====== + +Invite somebody to participate. This will create a guest account and a link with an +identifier to access this account, and send an invitation to the given email. + +The email is specified using ``-e EMAIL, --email EMAIL``, which can be used multiple times +to send the invitation to more than one address. + +You'll usually want to specify the name of the person you're inviting, using ``-n NAME, +--name NAME``, it may later be used in email sent or in the web page where your guest will +land. + +``-N HOST_NAME, --host-name HOST_NAME`` is used to specify the name of yourself (i.e. the +person which is inviting), it may be used in invitation message. + +You'll most of time have to specify the URL template using ``-u URL, --url URL``. This +will be used in the invitation email to construct the URL where your invitee will click. +You may use the string ``{{uuid}}`` in this template which will be replaced by the id +associated to the invitation. With Libervia, default invitation page is +``/g/``. + +The language of your guest can be specified using ``-l LANG, --lang LANG``, this is +notably useful if you have multilingual blog posts (e.g. for an event where people +speaking different languages are invited). + +The ``-x KEY VALUE, --extra KEY VALUE`` is used for extra data which depend on what you +are inviting your guests for. + + +example +------- + +Invite Louise, which is speaking French, to an event. The invitation is sent to her email +address ``louise_email@example.net``, is sent by Piotr, and must link to the Libervia +instance at ``https://www.example.org/g/``. We use here the ``event_uri`` extra key:: + + $ jp invitation create -n Louise -N Pierre -e louise_email@example.net -l fr -u "https://www.example.org/g/{uuid}" -x event_uri xmpp:pierre@example.org?;node=MnXe4ic2X8RUz6JAJuw4f9;item=org.salut-a-toi.event%3A0 + + +get +=== + +Get metadata for one specific invitation. You only have to specify the invitation id, and +you may use the option ``-j, --with-jid`` to also get the jid used for the invitation +(this will start the session of the invitee). + +example +------- + +Get invitation data for invitation with id ``okFec4gDz75My7iQAVTmsc``:: + + $ jp invitation get okFec4gDz75My7iQAVTmsc -j + + +modify +====== + +This work the same way as jp-invitation_create_, you only have to specify the ``id`` of the +invitation. + +If you use the ``--replace`` argument, all the invitation data will be replaced by the +ones you're specifying. + +example +------- + +Change the language of the invitee for the invitation ``okFec4gDz75My7iQAVTmsc`` for +Slovak:: + + $ jp invitation modify -l sk okFec4gDz75My7iQAVTmsc + + +list +==== + +List registered invitations. You may filter by the profile who made the invitation using +``-p PROFILE, --profile PROFILE``. +The invitations are shown by default using id as main data, and metadata below. + +example +------- + +List invitations:: + + $ jp invitation list diff -r fee60f17ebac -r 72583524cfd3 doc/jp/merge-request.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/merge-request.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,81 @@ +=============================================== +merge-request: create and manage merge requests +=============================================== + +Merge-request are used to propose some modifications to a project. They are generic and +are made to be used with several backends, but only Mercurial is implemented so far. + +To prepare a merge request with Mercurial, you just need to have a clone of the project, +and do your modifications (either directly, or in a bookmark, a branch, or a MQ patch). + +set +=== + +Create and publish a merge request. Once the modification on the project are done, simply +run the command from the repository (or specify its path with ``-r PATH, --repository +PATH``). If the project has set metadata (it can be done with a magic string in README), +you don't have to specify any service or node, it will be set automatically (but you still +can specify them if needed). + +You may associate one or more labels to your request using ``-l LABELS, --label LABELS``. + +By default, a confirmation is requested before publishing the request, you can publish +without confirmation by using the ``-f, --force`` flag. + +If you have already done a merge request and you just want to update it, check its id and +specify it with ``-i ITEM, --item ITEM``, this will override the previous request with the +new updated one. + +examples +-------- + +Publish a merge request (to be executed from the repository of the project you have +modified):: + + $ jp merge-request set + +Update an existing merge request, which has the id ``123`` (to be executed from the +reposiroty of the project you have modified):: + + $ jp merge-request set -i 123 + +Do a merge request for repository at path ``~/some_project``, specifying a label +indicating it's work in progress (WIP):: + + $ jp merge-request set -r ~/some_project --label WIP + + +get +=== + +Get and print one or more merge requests. By default only some metadata are shown (without +the patches), but you can use ``--verbose, -v`` to show details. + +examples +-------- + +Show some metadata of last 5 merge requests:: + + $ jp merge-request get -M 5 + +Display details for merge request with id 456:: + + $ jp merge-request get -v -i 456 + + +import +====== + +Import a merge request into your project. You mainly have to be in the project repository +(or specify it using ``-r PATH, --repository PATH``) and to specify the id of the patch to +import (using ``-i ITEM, --item ITEM``). The behaviour depends of the type of the patch, +for Mercurial, the patch will be imported as `MQ`_ patch. + +.. _MQ: https://www.mercurial-scm.org/wiki/MqExtension + +example +------- + +Import the merge request with id 321:: + + $ jp merge-request import -i 321 diff -r fee60f17ebac -r 72583524cfd3 doc/jp/message.rst --- a/doc/jp/message.rst Wed Sep 25 08:56:41 2019 +0200 +++ b/doc/jp/message.rst Tue Oct 01 22:49:06 2019 +0200 @@ -6,10 +6,12 @@ Message commands let you send chat messages or manage your server message archives. +.. _jp-message_send: + send ==== -send a message to a contact or a chat room. +Send a message to a contact or a chat room. ``stdin`` is used as message source. You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed. You can manage your encrypted session using ``encryption`` command. @@ -36,7 +38,7 @@ mam === -query archives using MAM. +Query archives using MAM. This command allows you to check message archive kept on the server (i.e. not the local copy). You usually want to specify a starting point, and a number of message to retrieve. If too many messages are available, you'll have to use RSM commands to navigate through the results. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/param.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/param.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,124 @@ +============================ +param: manage SàT parameters +============================ + +``param`` commands allows to retrieve or set parameters as well as to export/import them +to a XML file. + +Parameters are retrieve using a ``category`` and a ``name``, they are both case sensitive. + +``category`` is the name of the tabs that you see when you set parameters in a frontend +like Cagou or Libervia. + +.. note:: + + You need to have your session started to retrieve of modify parameters. If you can't + or are not willing to connect for any reason (e.g. no internet connection), you can + use the ``--start-session`` option to start the profile session without connecting it + to the XMPP server. + +get +=== + +Retrieve list of categories, parameters or a specific parameter value: + +- without argument, you'll get the list of categories +- with only a category specified, you'll get a list of parameters and their values +- with a category and a name, you'll get the value or requested attribute of the specified + parameters + +By default you'll get the value of the parameters, but you can request an other attribute +(for instance its ``type`` or ``constraint``) using the ``-a ATTRIBUTE, --attribute +ATTRIBUTE`` argument. + +You can set a security limit to retrieve only parameters allowed with this limit. +Security limit is an integer used in some frontends (like Libervia), to restrict +parameters modifiable by non privileged users. You can set it using ``--security-limit +SECURITY_LIMIT``, by default it is disabled (i.e. all parameters are returned). + +examples +-------- + +Get list of categories:: + + $ jp param get + +Get list of parameters in ``General`` category:: + + $ jp param get General + +Get JID set for default profile. It is set in ``Connection`` category, with the parameters +named ``JabberID`` (be careful with the case):: + + $ jp param get Connection JabberID + +Get the type of the ``check_certificate`` parameters in ``Connection`` category:: + + $ jp param get Connection check_certificate -a type + +Get the constraint of the ``Priority`` parameters in ``Connection`` category:: + + $ jp param get Connection Priority -a constraint + +set +=== + +As expected, this command set a SàT parameter. The ``category``, ``name`` and ``value`` +are needed as positional arguments. + +``--security-limit SECURITY_LIMIT`` can be used if you want an update to be rejected if +the parameter is not modifiable with this limit. This can be useful if you use ``jp`` from +an external tool and you want to limit damage risks, or for testing purpose. + +examples +-------- + +Use Markdown_ syntax for composition (e.g. for editing blog posts):: + + $ jp param set Composition Syntax markdown + +Try to change jid of the profile with a low security limit, this command should fail:: + + $ jp param set --security-limit 0 Connection JabberID some_random_jid@example.org + +.. _Markdown: https://daringfireball.net/projects/markdown/ + +.. _jp-param_save: + +save +==== + +Save the parameters structure to an external files. The parameters are saved as XML. The only +expected argument is the path to the destination file. + +.. note:: + + it's the parameters structure and not the parameters values which are saved. This is + low level method and most end users won't probably need it + +example +------- + +Save parameters structure to ``~/parameters.xml``:: + + $ jp param save ~/parameters.xml + +.. _jp-param_load: + +load +==== + +Load and merge the parameters structure from external XML files. The only expected +argument is the path to the source file. + +.. note:: + + it's the parameters structure and not the parameters values which is loaded and merged. + This is low level method and most end users won't probably need it + +example +------- + +Load and merge parameters structure from ``~/parameters.xml``:: + + $ jp param load ~/parameters.xml diff -r fee60f17ebac -r 72583524cfd3 doc/jp/ping.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/ping.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,20 @@ +========================================= +ping: get response time of an XMPP entity +========================================= + +``ping`` is more or less the equivalent of the command of the same name on most OSes, but +for XMPP. It send a `XEP-0199`_ PING and wait for the answer. When (and if) received, the +time to receive the answer is shown, else the time to receive the error message is shown. +This can be helpful to quickly test the connection with the server or a device. + +If you need to get only the response time (without text around), you may use ``-d, +--delay-only``. + +.. _XEP-0199: https://xmpp.org/extensions/xep-0199.html + +example +------- + +Get reponse time of a server:: + + $ jp ping example.org diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pipe.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pipe.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,43 @@ +================================================== +pipe: send/receive data stream through shell pipes +================================================== + +``pipe`` commands allow you to send or receive data stream through a Unix shell pipe. +Salut à Toi will create a network connection (using XMPP and Jingle) between you an your +contact. + +in +== + +Receive data stream. Data will be send to stdout, so it can be piped out or simply print +to the screen. You can specify bare jids of entities to accept stream for, by default all +streams are accepted. + +example +------- + +Receive a video stream, and redirect it to mpv_ so show the video:: + + $ jp pipe in | mpv - + +.. _mpv: https://mpv.io/ + +out +=== + +Send data stream. Data comes from stdin, so you may use pipe in something or just write +some text. + +The only expected argument is the full jid of the device where the stream must be piped +out. + +example +------- + +Send a video to louise:: + + $ jp pipe out louise@example.org/sat < some_video.webm + +Send output from ``cal`` command to louise:: + + $ cal | jp pipe out louise@example.org/sat diff -r fee60f17ebac -r 72583524cfd3 doc/jp/profile.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/profile.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,191 @@ +============================= +profile: SàT profile handling +============================= + +Profiles are the names associated with accounts in SàT, for more informations you can +check :ref:`glossary`. The `profile` commands help you create/delete/modify and manage +profiles. + + +connect +======= + +Unsurprisingly this command connects your profile, i.e. log-in your XMPP account. This +command uses :ref:`jp-common_profile` common commands, so you can use either ``-c, +--connect`` to connect to XMPP server, or ``--start-session`` if you want to start SàT +profile session without connecting to XMPP server (for instance if you want to modify +parameters without connecting to XMPP server). + +Note that :ref:`jp-common_profile` common commands are available in commands needing a +connected profile, ``jp profile connect`` is interesting if you only want to connect your +profile/start a session. + +example +------- + +Connect the default profile:: + + $ jp profile connect -c + + +disconnect +========== + +Disconnect your profile from XMPP server. There is no option beside the +:ref:`jp-common_profile` common options. + +example +------- + +Disconnect the profile ``pierre``:: + + $ jp profile disconnect -p pierre + + +create +====== + +Create a new SàT profile. The only mandatory argument is the profile name, but you'll +probably want to associate an XMPP jid with ``-j JID, --jid JID`` and a profile password +with ``-p PASSWORD, --password PASSWORD``. By default, profile password will be used for +XMPP password (see note below), but you may specify XMPP password with ``-x PASSWORD, +--xmpp-password PASSWORD``. + +SàT is also capable to manage components, which can be seen as XMPP server independent +plugins. To create a component profile, you'll have to use ``-C COMPONENT, --component +COMPONENT`` where ``COMPONENT`` is the component entry point (check the documentation of +the component that you want to use to get its entry point). + +.. note:: + + profile password and XMPP password are not the same: the profile password is the + password of your SàT profile, while the XMPP password is the one checked by your XMPP + server. If specify a jid with ``--jid`` and you don't specify an XMPP password, the + profile password will be used by default. + + The reason to have distinct password is that you may use a different password for + profile, including an empty one if you want SàT to connect your profile without + having to enter a password. Also the XMPP password is encrypted in database using the + profile password (which is not stored in database, only a hash is kept). + + +.. note:: + + passwords in jp are currently specified directly on the command-line and not prompted, + this is not safe from a security point of view as people can see it on the screen, it + may stay in your shell history, or visible on process list. Keep that in mind if you're + in a public environment or on a public machine. This will be improved for SàT 0.8. + +examples +-------- + +Nestor wants to create a profile for its account on ``example.org``, he specifies a +profile password only, so it will also be used as the XMPP password:: + + $ jp profile create nestor -j nestor@example.org -p some_password + +Create a component profile for the file sharing component (whose entry point is +``file_sharing``). The jid of the service is specified with ``--jid`` (note that we don't +use a node as it is a jid of a component) and the ``--xmpp-password`` is the shared +secret. Here the profile password is kept empty to not have to enter manually the XMPP +password each time we connect the service:: + + $ jp profile create file_sharing -j files.example.org -p "" --xmpp-password + some_shared_secret -C file_sharing + + +default +======= + +This command simply prints the default profile (i.e. the profile used when none is +specified with ``-p PROFILE, --profile PROFILE``). The default profile is either the first +one that you've created, or the one you have explicitly set as default. + +example +------- + +Print default profile:: + + $ jp profile default + + +delete +====== + +Delete a profile and all its associated data. This delete the SàT profile and associated +data (i.e. local data), but doesn't request the XMPP server to delete anything. + +By default a confirmation is requested, use ``-f, --force`` to avoid it (be cautious with +this option). + +example +------- + +Delete the profile of Pierre:: + + $ jp profile delete pierre + + +info +==== + +Display information on a profile. For now, only the registered jid is shown, and +optionally the XMPP password. To display the XMPP password, use ``--show-password`` but be +careful that nobody can see your screen, as **this password will be shown in clear text**. + +example +------- + +Show jid and XMPP password for default profile:: + + $ jp profile info --show-password + + +list +==== + +Show all profiles. You can use ``-c, --clients`` to show only client profiles, and ``-C, +--components`` to show only component profiles. + +example +------- + +Show all profiles:: + + $ jp profile list + + +modify +====== + +Update an existing profile. You can use this command to change profile password (with ``-w +PASSWORD, --password PASSWORD``) or even disable it (with ``--disable-password``, this is +equivalent to using an empty profile password ; be cautious with this option, see the note +below). + +With ``-j JID, --jid JID`` and ``-x PASSWORD, --xmpp-password PASSWORD`` you can change +XMPP jid and password. + +This command can also be used to select the default password, use the ``-D, --default`` +flag for that. + +.. note:: + + Be cautious with ``--disable-password`` that means that no password will be needed with + any frontend of SàT to use this profile, and that XMPP password will be easy to + retrieve for anybody having an access to the machine where SàT is installed + +examples +-------- + +Pierre has changed server, he can update his jid and password like this:: + + $ jp profile modify -p pierre -j pierre@example.org -x new_password + +Use ``louise`` as default profile:: + + $ jp profile modify -p louise -D + +Disable profile password for default profile (be cautious, see the note above):: + + $ jp profile modify --disable-password diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,352 @@ +.. _jp-pubsub: + +========================= +pubsub: PubSub management +========================= + +PubSub commands are low level command to handle a PubSub Service. +They are using the generic pubsub arguments + +For most of those commands, :ref:`pubsub_common` commands are used to specify the +destination item. + +set +=== + +Publish a pubsub item. + +``stdin`` is used to get the raw XML of the payload of the item to publish. + +example +------- + +Create an item with a custom note XML:: + + $ echo 'this is a note' | jp pubsub set -n "notes" + +get +=== + +Retrieve items from specified node. Default output is prettified and highlighted XML. + +example +------- + +Retrieve the last 5 notes from our custom notes node:: + + $ jp pubsub get -n notes -m 5 + +delete +====== + +Delete an item from a node. If ``-N, --notify`` is specified, subscribers will be notified +of the item retraction. + +By default a confirmation is requested before deletion is requested to the PubSub service, +but you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Delete item with id ``123456`` from a node:: + + $ jp pubsub delete -n test_node -i 123456 + +edit +==== + +Edit the raw XML of an item payload using your local editor (the one set in ``$EDITOR``). + +If you don't change anything or publish an empty blog post, the edition will be cancelled. + +:ref:`draft_common` commands can be used. + +example +------- + +Edit the last note in our custom node:: + + $ jp pubsub edit -n notes -L + +subscribe +========= + +Subscribe to a node. + +Subscription is used to get notifications from the node in case of new/updated item or +deletion. + +example +------- + +Subscribe to an information blog:: + + $ jp pubsub subscribe -n informations -s pubsub.example.net + +unsubscribe +=========== + +Unsubscribe from a node. + +example +------- + +Unsubscribe from an information blog:: + + $ jp pubsub unsubscribe -n informations -s pubsub.example.net + +subscriptions +============= + +Retrieve subscriptions for all nodes on a service. + +``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if +it has subscription with multiple subIDs). + +example +------- + +Retrieve all subscriptions on a pubsub service:: + + $ jp pubsub subscriptions -s pubsub@example.net + +affiliations +============= + +Retrieve affiliations for all nodes at a service. + +``-n NODE, --node NODE`` can be used to request affiliation for a specific node. + +examples +-------- + +Retrieve all affiliations at a pubsub service:: + + $ jp pubsub affiliations -s pubsub@example.net + +Retrieve affiliation for the ``notes`` node:: + + $ jp pubsub affiliations -s pubsub@example.net -n notes + +search +====== + +Search items corresponding to one or more filter(s). + +``search`` will check all items (or some of them according to options used) from one or +several nodes (several nodes can be checked if recursion is used, see below). For each +item the given filters will be checked, and all corresponding items will be returned. + +This is a resource intensive method (both for server and client), use with caution, and +use MAM to do searching when suitable. + +filters +------- + +To do a search you one or more filters. Filters are checked in the order in which they are +specified. You can use 4 kinds of filters: + +``-t TEXT, --text TEXT`` + do a full-text search. If *TEXT* is appearing anywhere in the item (including in XML + tags or arguments), the item is selected + +``-r EXPRESSION, --regex EXPRESSION`` + do a regular expression search. `Python standard re module`_ is used internally, so you + can use its syntax. + +``-x XPATH, --xpath XPATH`` + use an `XPath version 1.0`_ expression to filter the query. You can have a look at + `Wikipedia XPath page`_ for a user friendly introduction. + +``-P PYTHON_CODE, --python PYTHON_CODE`` + use a Python expression to do a test. The expression must return a boolean (``True`` to + keep item, ``False`` otherwise). From within the Python expression 3 variables are + defined: ``item`` which contain the raw item as a string, and ``item_xml`` which is the + parsed XML as an lxml ``etree.Element`` and ``etree`` which is the ``lxml.etree`` module. + +.. _Python standard re module: https://docs.python.org/3.7/library/re.html +.. _XPath version 1.0: https://www.w3.org/TR/1999/REC-xpath-19991116/ +.. _Wikipedia XPath page: https://en.wikipedia.org/wiki/XPath + +filter modifiers +---------------- + +Before each filter you can specify one or more filter modifiers. A modifier will change +filter behaviour, it's a flag which can be used either without argument (then it will +activate the flag), or with an explicit boolean value (i.e. ``true`` or ``false``). + +The available filters are: + +``-C [BOOLEAN], --ignore-case [BOOLEAN]`` + (don't) ignore case. Filters are normally case sensitive, this modifier change this + behaviour. + +``-I [BOOLEAN], --invert [BOOLEAN]`` + (don't) invert effect of following filters. This is applying a logical ``NOT`` to the + filter. This means that instead of keeping item matching the filter, it will keep the + items which are **not** matching the filter. + +``-A [BOOLEAN], --dot-all [BOOLEAN]`` + (don't) use `DOTALL`_ option for regex. This filter only makes sense before a + ``--regex`` expression. + +``-k [BOOLEAN], --only-matching [BOOLEAN]`` + (don't) keep only the matching part of the item. Normally the whole item is returned, + with this flag, only the part matching the filters are kept. + +.. _DOTALL: https://docs.python.org/3.7/library/re.html#re.DOTALL + +actions +------- + +Once filters are set, you may indicate what do to with the found items. By default they +are printed, but you can also use an other jp command, or even an external tool. + +The following actions are available: + +``print`` (default) + pretty print the found items. + +``exec`` + use the given jp command on each found item. Everything after the ``exec`` is used to + indicate the command and arguments to use (you must not specify ``jp``, use the command + directly). The service, node and item will be set to match the found item. + +``external`` + pipe the raw XML of each item to the given command. Everything after the ``external`` + action is used to indicate the command and arguments to use. + +recursive search +---------------- + +By default, only items in the given node will be filtered, but if you specify a recursion +depth > 0 (using ``-D MAX_DEPTH, --max-depth MAX_DEPTH``), every node linked in item will +be checked too, then node linked in linked item and so on until depth level is reached. + +For instance, if you want to find all comments of a blog node containing an http(s) link, +you can do that:: + + $ jp pubsub search -n urn:xmpp:microblog:0 -s user@example.net -D 1 -r 'https?://' + +examples +-------- + +Finding all items containing the text "something interesting" in personal blog:: + + $ jp pubsub search -n urn:xmpp:microblog:0 -M -1 -t "something interesting" + +Find which blog items in the last 20 have a body with less than 200 characters (note that +body can be either ```` or ``<content>``, see `XEP-0277`_ for details). Here we use +a python expression on the text of the body to count the number of characters:: + + $ jp pubsub search -n urn:xmpp:microblog:0 -M 20 --python "len((item_xml.find('.//{http://www.w3.org/2005/Atom}content[@type=\"text\"]') or item_xml.find('.//{http://www.w3.org/2005/Atom}title[@type=\"text\"]')).text) < 200" + +Find items published by ``toto@example.net`` among last 30 on a blog node, and use +``pubsub blog`` command to retrieve id and title. We use ``-N`` to specify the ``pubsub`` +namespace which is used in the XPath expression, then we use ``exec`` to run ``blog get -k +title -k id`` on found items:: + + $ jp pubsub search -n some_blog_node -s pubsub.example.net -M 30 -N pubsub http://jabber.org/protocol/pubsub -x '/pubsub:item[starts-with(@publisher, "toto@example.net")]' exec blog get -k title -k id + +Find items which have **NOT** a title among last 30 items in our personal blog. As +explained in `XEP-0277`_ Atom's ``<title>`` is always used (even if there is only a body +and no title), so we actually look for items without ``<content>``. We do that with an +XPath looking for this ``atom:content`` element, then we use the ``-I [BOOLEAN], --invert +[BOOLEAN]`` to filter out elements which match.:: + + $ jp pubsub search -n urn:xmpp:microblog:0 -M 30 -I -x //atom:content -N atom http://www.w3.org/2005/Atom + +Display authors names from last 10 items and their comments, using the ``-k [BOOLEAN], +--only-matching [BOOLEAN]`` modifier to only display the data we need. We use ``-D 1`` to +do a recursive search of level 1, which will also look into comments nodes (using last 10 +items there too):: + + $ jp pubsub search -n urn:xmpp:microblog:0 -M 10 --only-matching -x //atom:author/atom:name -N atom http://www.w3.org/2005/Atom -D 1 + +.. _XEP-0277: https://xmpp.org/extensions/xep-0277.html + +transform +========= + +Modify items using an external command. + +``transform`` will retrieve requested items, and will send each of them to the standard +input (stdin) of the specified command. The output of the command will be used, it can be +3 things: + +- a raw XML of the modified item, in which case the item will be republished +- the string ``SKIP``, in which case the item will be ignored +- the string ``DELETE``, in which case the item will be retracted + +By default a dry run is done, which means that no item is modified or deleted. To actually +do the transformation, you have to use ``--apply`` argument. + +If you have to modify the ``publisher`` of an item, you need specific privileges. The +``--admin`` allows you do to that, but it must be supported by your PubSub service +(currently only ``SàT PubSub`` supports this non standard feature). + +To modify all items of a node, use the ``-A, --all`` option. This will use `RSM`_ +repetitively until all items are treated. Of course that means that your PubSub service +must support RSM. The items being republished, they will reappear on top of your node, +that's why it is recommended to use ``--order-by creation`` option when supported by the +service, to keep consistent order and avoid transforming the same items several times. + +If the command you're using exit with a non zero code, the process will stop. Use ``-I, +--ignore_errors`` if you want to continue transformation even if an non zero code is +returned. + +.. _RSM: https://xmpp.org/extensions/xep-0059.html + +example +------- + +Imagine that you want to replace all occurrences of "sàt" by "Salut à Toi" in your personal blog. You first create a Python script like this: + +.. sourcecode:: python + + #!/usr/bin/env python3 + + import sys + item_raw = sys.stdin.read() + if not "sàt" in item_raw: + print("SKIP") + else: + print(item_raw.replace("sàt", "Salut à Toi")) + +And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make is executable +with ``chmod +x ~/expand_sat.py``). + +To be sure it's safe, you can first do a dry-run and check the result:: + + $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py + +Once you have checked that you have the expected behaviour, you can apply the +transformations:: + + $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py + +And that's it. You can use the same technique for more complex transformations, including +modifying the XML (with Python, you can easily do that with standard +``xml.etree.ElementTree`` module or with ``lxml.etree``). + +uri +=== + +Build an XMPP URI linking to a PubSub node or item. + +example +------- + +Build a link to personal blog:: + + $ jp pubsub uri -n urn:xmpp:microblog:0 + +node +==== + +Subcommands for node management. Please check :ref:`jp-pubsub_node`. + +hook +==== + +Subcommands for hooks management. Please check :ref:`jp-pubsub_hook`. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub_hook.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub_hook.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,96 @@ +.. _jp-pubsub_hook: + +==================================== +pubsub/hook: PubSub hooks management +==================================== + +``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks +are user actions launched on specific events. + +3 types of hooks can be used: + +``python`` + A Python module is expected as argument. The module must be available in Python path, + and it must have a ``hook`` function. + +``python_file`` + A path to a Python script is expected as argument. The script must contain a ``hook`` + function. + +``python_code`` + Python code which will be directly executed. 3 variables will be set: ``host`` which + contain the main SàT instance, ``client`` which contain the session attached to the + profile, and ``item`` which contain the item attached to the event. + +.. note:: + + Hooks are executed in SàT context, and must be asynchronous. If they block, the whole + SàT execution will be blocked. They have access to everything, so don't run a code that + you don't absolutely trust. + +.. note:: + + Only ``python_file`` type is currently implemented + +.. note:: + Hook is an experimental feature, the way to use it may change in the future. + +create +====== + +Create a hook of given type. Type is specified with ``-t {python,python_file,python_code}, +--type {python,python_file,python_code}`` and a positional arguments is expected, which +depends on the chosen type. + +By default the hook is temporary (it will be lost if the profile is disconnected), but you +can make is persistent accross reconnexions if you use the ``-P, --persistent`` argument. + +example +------- + +Install a persistent hook on blog node, using the Python script named +``do_something_neat.py`` in ``$HOME`` directory:: + + $ jp pubsub node hook create -n urn:xmpp:microblog:0 -t python_file --persistent ~/do_something_neat.py + +delete +====== + +Delete one hook or all of them. To delete a hook, specify its type and argument (the that +you have used with ``create``). If you use empty ``--type`` and ``--arg`` all hooks will +be removed. + +example +------- + +Delete the ``do_something_neat.py`` hook:: + + $ jp pubsub node hook delete -n urn:xmpp:microblog:0 -t python_file --arg ~/do_something_neat.py + +list +==== + +List registered hooks. The output will give the following informations: + +service + PubSub service on which the hook is attached. + +node + PubSub node on which the hook is attached. + +type + hook type + +arg + hook arguments (dependant of hook type) + +persistent + boolean indicating is the hook persist accross sessions. + +example +------- + +Get PubSub hooks registered for this profile in JSON:: + + $ jp pubsub hook list -O json + diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub_node.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub_node.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,124 @@ +.. _jp-pubsub_node: + +==================================== +pubsub/node: PubSub nodes management +==================================== + +``node`` is a subcommands grouping all PubSub commands related to node management. For +details on ``pubsub`` command itself, refer to :ref:`jp-pubsub`. + +info +==== + +Get settings of the node. Use ``-k KEYS, --key KEYS`` to select data to print. + +examples +-------- + +Get informations on our personal microblog node:: + + $ jp pubsub node info -n urn:xmpp:microblog:0 + +Only print ``access_model`` and ``publish_model``:: + + $ jp pubsub node info -n urn:xmpp:microblog:0 -k access_model -k publish_model + +create +====== + +Create a node. Node configuration can be specified using ``-f KEY VALUE, --field KEY +VALUE`` where ``KEY`` is a pubsub option. By default the ``pubsub#`` prefix will be +appended, as it is used with standard options (see `XEP-0060`_ for more details); to +change this behaviour, use the ``-F, --full-prefix`` flag. + +.. _XEP-0060: https://xmpp.org/extensions/xep-0060.html + +example +-------- + +Create a node called ``notes`` with a ``whitelist`` access model (so only you and people +you may authorize later can access it):: + + $ jp pubsub node create -n notes + +purge +===== + +Remove all items from a node (but don't delete the node). + +A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Remove all items from a blog comments node (in other words, removing all comments while +letting the node so people can add new comments):: + + $ jp pubsub node purge -n "urn:xmpp:microblog:0:comments/123-456-789" + +delete +====== + +Delete a node (note that this will delete definitively all items that where published to +this node). + +A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option. + +example +------- + +Delete the ``temporary_notes`` node:: + + $ jp pubsub node delete -n temporary_notes + +set +=== + +Update a node configuration. + +Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` argument +where ``KEY`` is a PubSub option. If ``KEY`` doesn't start with ``pubsub#`` prefix, it is +added automatically, except if ``-F, --full-prefix`` argument is used (in which case the +``KEY`` is used as specified. + +example +------- + +Make the ``public_notes`` node accessible to the world:: + + $ jp pubsub node set -n public_notes -f access_model open + +import +====== + +Import a raw XML containing items to create in the node. The path to the XML file is used +as positional argument. + +The XML file must contain full `<item>` element for each item to import. The output of ``pubsub get`` can be used directly. + +If you want to change publisher of one or more items (i.e. if you want to use an other ``jid`` than the jid of the profile as publisher), you must use the ``--admin`` arguments. This needs a PubSub service supporting this feature (and you must of course be an administrator of this service). The new publisher must be allowed to publish to the node. + +example +------- + +Import a node backup which has previously been saved using ``jp blog get -M -1 -n +some_node > some_node_backup.xml``:: + + $ jp pubsub node import -n some_node ~/some_node_backup.xml + +.. note:: + + If your node is big, -M 1 option is not adapted as it will get all items at once and + may be blocked by your server stanza size limit. The possibility to use RSM to + retrieve all items by pages is planned in a future version. + +affiliations +============ + +Subcommands for node affiliations management. Please check :ref:`jp-pubsub_node_affiliations`. + +subscriptions +============= + +Subcommands for node subscriptions management. Please check +:ref:`jp-pubsub_node_subscriptions`. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub_node_affiliations.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub_node_affiliations.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,40 @@ +.. _jp-pubsub_node_affiliations: + +======================================================= +pubsub/node/affiliations: nodes affiliations management +======================================================= + +``affiliations`` is a subcommand handling the affiliations of a node (not to be confused +with ``pubsub affiliations`` which handle the affiliations of a PubSub service). + +get +=== + +Retrieve entities affiliated to this node and their role. + +example +------- + +Get affiliations of a node:: + + $ jp pubsub node affiliations get -n some_node + +set +=== + +Set affiliation of an entity on a node. Affiliations are specified with ``-a JID +AFFILIATION`` argument. Check `XEP-0060 affiliations`_ for allowed values for +``AFFILIATION``. Use ``none`` to remove an affiliation. + +.. _XEP-0060 affiliations: https://xmpp.org/extensions/xep-0060.html#affiliations + +example +------- + +If we have a whitelisted node ``some_whitelisted_node``, we can allow +``louise@example.net`` to publish on it (by setting her role as ``publisher``), and +``pierre@example.net`` to access it (by setting his role as ``member``) using the +following command:: + + $ jp pubsub node affiliations set -n some_whitelisted_node -a louise@example.net + publisher -a pierre@example.net member diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub_node_schema.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub_node_schema.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,59 @@ +.. _jp-pubsub_node_schema: + +========================================= +pubsub/node/schema: nodes schema handling +========================================= + +``node schema`` is an experimental feature to associate a data form with a PubSub node, and +reject items not following this form. This feature is currently only available with SàT +PubSub. + +Those commands can only be used by an owner of the node. + +set +=== + +Set the schema of a node. The raw schema is written directly as positional argument. + +example +------- + +Set the schema for tickets node using the file ``tickets_schema.xml`` from ``$HOME`` +directory. Shell substition is used here to put the content of the file in the positional +argument:: + + $ jp pubsub node schema set -n org.salut-a-toi.tickets:0 -s pubsub.example.org "$(<~/test_schema.xml)" + + +edit +==== + +Edit the schema of a node using your local editor (the one set in ``$EDITOR``). + +If you don't change anything or publish an empty schema, the edition will be cancelled. + +:ref:`draft_common` commands can be used. + +example +------- + +Edit the tickets node schema:: + + $ jp pubsub node schema edit -n org.salut-a-toi.tickets:0 -s pubsub.example.org + + +example +------- + +get +=== + +Retrieve schema of a node. + +example +------- + +Get schema of tickets and save it to a file named ``tickets_schema.xml`` in ``$HOME`` +directory:: + + $ jp pubsub node schema get -n org.salut-a-toi.tickets:0 -s pubsub.example.org > ~/tickets_schema.xml diff -r fee60f17ebac -r 72583524cfd3 doc/jp/pubsub_node_subscriptions.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/pubsub_node_subscriptions.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,43 @@ +.. _jp-pubsub_node_subscriptions: + +======================================================== +pubsub/node/affiliations: nodes subscriptions management +======================================================== + +``subscriptions`` is a subcommand handling the subscription to a node. + +Those commands can only be used by an owner of the node. + +get +=== + +Retrieve subscriptions to a node. + +example +------- + +Get subscription from ``some_node``:: + + $ jp pubsub node subscriptions get -n some_node + +set +=== + +Set subscriptions to a node. Subscriptions are specified with ``-S JID [SUSBSCRIPTION] +[JID [SUSBSCRIPTION] ...], --subscription JID [SUSBSCRIPTION] [JID [SUSBSCRIPTION] ...]`` +where ``JID`` is the jid of the entity to change subscription state, and ``SUBSCRIPTION`` +is a subscription state (on of ``subscribed``, ``pending``, ``none``) as specified in +`XEP-0060 Subscription State`_. If ``SUBSCRIPTION`` is not specified, it default to +``subscribed``. + +.. _XEP-0060 Subscription State: https://xmpp.org/extensions/xep-0060.html#substates + +example +------- + +Subscribe Louise with her new address at ``louise@example.org`` and remove her +subscription from old ``louise@example.com``:: + + $ jp pubsub node subscriptions set -n some_node -S louise@example.org subscribed louise@example.com none + + diff -r fee60f17ebac -r 72583524cfd3 doc/jp/roster.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/roster.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,110 @@ +================================ +roster: manager an entity roster +================================ + +"Roster" is the name used in XMPP for the contact list. In addition to list of contacts, +you have also data like subscription information or groups associated to a contact. + +Groups are simple strings associated to one or more contacts (e.g. "friends" or "family"). + +Subscription is the mechanism to get presence information of an entity. When you add a +contact to your roster, most XMPP clients also do a presence subscription request, than +the entity may accept or deny. If a presence subscription is accepted, the subscribed user +can see when the other entity is online, and its presence status. + +get +=== + +Show the current roster. By default only a display name and JIDs are displayed, but you +can increase verbosity to also display groups, or all other metadata. + +The short name shown next to jid is either the ``name`` specified in roster, or the node +part of the jid. If none of them exist, only the entity JID is shown. + +The following metadata may be displayed: + +groups + group the entity belong too +ask + true if a presence subscription request has been sent (but not answered yet) +from + the contact has a subscription to user presence (i.e. your contact can see when you're + online and your presence status) +to + the user has a subscription to the contact presence (i.e. you can see when you're + contact is online and his/her presence status) + +examples +-------- + +Get roster of default profile and display groups:: + + $ jp roster get -v + +Get roster of default profile and display all metadata:: + + $ jp roster get -vv + +Get roster or default profile and show the result in JSON:: + + $ jp roster get -O json + +stats +===== + +Show some statistics about the profile roster. The number of contacts per server is shown, +with a percentage of contacts on this server compared to the total number of contacts. +This can notably be helpful to see if there is a concentration of your contacts in a +specific server or gateway. + +Other more or less useful numbers are shown, they are self explaining. + +example +------- + +Get statistic for the default profile:: + + $ jp roster stats + +purge +===== + +This command is used to remove from the roster all contacts which have no subscription or +only partial subscription. + +By default, only contacts without subscription at all are removed. With ``--no_from`` you +also remove contacts which have no subscription to you (but you have a subscription to +them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but +who are subscribed to you). + +example +------- + +Remove all contacts from default profile which have no subscription at all or from which +the default profile is not subscribed to:: + + $ jp roster purge --no_to + +resync +====== + +SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on +client connection. This means that once the roster has been retrieved, on each following +connection, only the difference of contacts (i.e. which new or removed contacts) is +received. + +This command does a full resynchronisation of the roster, or in other words it requests +the whole roster and save it, replacing the list built with versioning. ``resync`` is +mostly useful for developers and end-user should not need this command, as roster +versioning is supposed to work fine and the roster should be synchronised correctly on +startup. But if for any reason you suspect that your current roster list is corrupted, you +may use it to be sure that a full resynchronisation is done. + +.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6 + +exemple +------- + +Do a full resynchronisation of default profile's roster:: + + $ jp roster resync diff -r fee60f17ebac -r 72583524cfd3 doc/jp/shell.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/shell.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,208 @@ +======================== +shell: use SàT with REPL +======================== + +``shell`` launch a read–eval–print loop (REPL) with some helpers to launch jp commands. +This is useful if you are willing to a session when you'll use several commands in a row +(for e.g. to inspect something on a PubSub service). + +start the shell +=============== + +To start the shell, you just have to enter ``jp shell``. You can eventually specify a +profile to use an other one than the default one by entering ``jp shell -p +<some_profile>``. + + +.. _jp-shell_use: + +use the shell +============= + +Once in the shell, you can launch a command by entering it as usual (without having to +specify ``jp``). For instance to get last 2 blog posts from your personal blog, you just +have to enter:: + + > blog get -m 2 + +There are 2 kinds of commands in the shell: + +- **shell commands** which are command to manipulate the shell itself +- **jp commands** which are the classic commands that you use with jp + +The most important thing to remember is that you can use ``?`` (or ``help`` which is +equivalent) to get the list of commands (shell + jp), and ``?<command>`` (or ``help +<command>``) to get information on a shell command. For jp commands, you can use the usual +``--help`` argument. + +You may move in the commands hierarchy using ``cmd`` which can be seen as something +roughly equivalent to ``cd`` for the filesystem. for instance if you know you'll work with +XMPP blogs, you can enter:: + + > cmd blog + +Then you'll be in the blog hierarchy, you can check that by entering ``?``. From there you +can use blog commands directly, like in this example to retrieve last 2 blog posts:: + + blog> get -m 2 + +You can even go further, e.g. if you know that you'll do several ``get`` command (in this +can you'll only have to specify the arguments of ``get``):: + + blob> cmd get + blog/get> -m 2 + +You can use ``/`` with ``cmd``, including as first character to indicate that you want to +start from root:: + + blog/get> cmd /pubsub + pubsub> cmd node/info + +Similarly, you can use ``..`` to move to parent command:: + + pubsub/node/info> cmd .. + +On of the interesting feature of shell is that you can fix an argument, i.e. indicate +the value to use in the next commands. For instance if you're willing to work on a +specific node, you can set its value with ``use``:: + + blog> use node some_interesting_node + +Then you won't have to specify it anymore for each command. The name of the argument to +fix must be the long form. To check which arguments are fixed, just enter ``use`` without +argument. If an argument is fixed but not used in a command, it will be ignored. + +To clear a fixed argument, you have the ``use_clear`` command. To clear the ``node`` +argument set above, just enter:: + + blog> use_clear node + +Without argument, all fixed arguments will be cleared. + + +Shell commands +============== + +Below is a description of shell commands. + + +cmd +--- + +Move in the command hierarchy, this avoid to type again a command if you know you'll use +it several times. See jp-shell_use_ for explanation and examples + +do +-- + +Launch a jp command. By default the command is launched if you enter directly its name and +arguments, but if a command or argument conflict with a shell command, the shell command +will be launcher instead. The ``do`` command avoid such a situation by always launching a +jp command:: + + > do blog get -m 2 + +exit +---- + +Quit the shell (alias of ``quit``). + +help (alias ``?``) +------------------ + +Give information on available commands or on a specific command, see jp-shell_use_ for +more explanations. + +examples +^^^^^^^^ + +Get general help:: + + > ? + +Get help on ``do`` command:: + + > ?do + +quit +---- + +Quit the shell + +shell (alias ``!``) +------------------- + +Launch an external command. + +example +^^^^^^^ + +Print a calendar with ``cal``:: + + > !cal + +use +--- + +Fix the value of an argument, which will then be set for all following commands, see +jp-shell_use_ for more explanations. + +Without argument, show all fixed arguments + +examples +^^^^^^^^ + +Fix the PubSub node (the long name of the argument is used, so it will go to ``--node``):: + + pubsub> use node some_intersting_node + +Show all fixed arguments:: + + > use + +use_clear +--------- + +Unfix the value of an argument (i.e. use the normal default value). Without argument, +it unfixes all arguments. + +examples +^^^^^^^^ +Clear the node:: + + pubsub> use_clear node + +Clear all arguments:: + + > use_clear + +verbose +------- + +Without argument, show if verbose mode is activated. With an argument evaluating to a +boolean, activate or deactivate this mode. + +In verbose mode, the fixed arguments and the command launched are printed before launching +a jp command. + +examples +^^^^^^^^ + +Show if verbose mode is activated:: + + > verbose + +Activate verbose mode:: + + > verbose on + +version +------- + +Print current version of jp/Salut à Toi. + +whoami +------ + +Show the name of the connected profile (the one set with ``--profile`` when launching the +shell). This profile will be used as default profile. diff -r fee60f17ebac -r 72583524cfd3 doc/jp/ticket.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/ticket.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,72 @@ +================================= +ticket: create and manage tickets +================================= + +Ticket is a generic tools to create items with metadata and states (where state can be +``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs +management. + +get +=== + +Retrieve one or more tickets and display them. A project may use magic string in README to +indicate PubSub service and node to use, in which case use just need to be in the +directory of the project. + +examples +-------- + +Retrieve last 5 tickets (ordered by creation) from a project using magic string in README:: + + $ jp ticket get -m 5 -o creation + +Retrieve the ticket with id ``123`` on service ``pubsub.example.org``:: + + $ jp ticket get -s pubsub.example.org -i 123 + + + +import +====== + +Import tickets from an external source. This works in the same way as +:ref:`jp-blog_import`: you need to specify an importer and a data location. If you let +both positional argument empty, you'll get list of importers, if you specify importer but +not data location, you'll get a description on how the importer works. + +If you want to see a progress bar for the import, use the ``-P, --progress`` option, this +is recommended for most imports. + +Some importers may have specific option (check description for details), you can specify +them with ``o NAME VALUE, --option NAME VALUE`` + +When you import a ticket, the ticket will be created according to the schema of the PubSub +node. By default, the metadata of the original ticket will be put to the one of the same +name in the dest PubSub item. But of course the schema of your destination PubSub node may +differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD +DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done +(``IMPORTED_FIELD is the name of the field in the original ticket, while ``DEST_FIELD`` if +the name of the field in your node schema). + + +examples +-------- + +Get list of ticket importers:: + + $ jp ticket import + +Get description of ticket importer for Bugzilla:: + + $ jp ticket import bugzilla + +Import tickets from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the +``pubsub.example.org`` PubSub service. We use default tickets node and want a progression +bar:: + + $ jp ticket import -P -s pubsub.example.org ~/bugzilla_export.xml + +Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to +the field ``assigned_to`` in our schema:: + + $ jp ticket import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml diff -r fee60f17ebac -r 72583524cfd3 doc/jp/uri.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/uri.rst Tue Oct 01 22:49:06 2019 +0200 @@ -0,0 +1,39 @@ +================================ +uri: XMPP URI parsing/generation +================================ + +URI commands are helper to easily parse/build XMPP URIs. + +parse +===== + +Parse an XMPP URI, and print different parts. + +When possible, the ``type`` of URI is shown (e.g. ``pubsub``) and the ``sub_type`` (e.g. +``microblog``). + +The ``path`` is always displayed (see `RFC 5122 Path section`_ for details). + +If suitable, you'll also get data like ``node`` (for a PubSub URI). + +.. _RFC 5122 Path section: https://tools.ietf.org/html/rfc5122#section-2.4 + +examples +-------- + +Parse a blog URI:: + + $ jp uri parse "xmpp:somebody@example.org?;node=urn%3Axmpp%3Amicroblog%3A0" + +build +====== + +Build an XMPP URI according to arguments. 2 positional arguments are expected: ``type`` +and ``path``. For now, only ``pubsub`` type is supported. + +examples +-------- + +Build XMPP URI for a blog:: + + $ jp uri build pubsub somebody@example.org -f node urn:xmpp:microblog:0 diff -r fee60f17ebac -r 72583524cfd3 doc/overview.rst --- a/doc/overview.rst Wed Sep 25 08:56:41 2019 +0200 +++ b/doc/overview.rst Tue Oct 01 22:49:06 2019 +0200 @@ -132,6 +132,7 @@ You can check :doc:`jp documentation <jp/index>` documentation for more details. +.. _glossary: Glossary ========