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, pubsub 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.
-f KEY VALUE, --field KEY VALUE
can be used to specify publish options, i.e. option
which must be set if the node already exists, or used if the node is to be created, see
XEP-0060 §7.1.5 for details.
In the same way as for create, -F, --full-prefix
can be used if
you need to specify the full option name.
To publish an end-to-end encrypted item, you can use the -e, --encrypt
flag, and
share secrets with pubsub/secret: share, revoke or rotate node secrets. Please read
Pubsub Encryption for more details.
You can encrypt a single item to targeted entities with the --encrypt-for
flag (not
to be confused with --encrypt
which is used when a whole node is encrypted). Please
read Pubsub Encryption for more details.
To cryptographically sign an item, you can use the -X, --sign
flag (a mnemonic way
to remember the short option is to think of a cross made as a signature on a document).
Signature can then be checked with pubsub/signature: Sign and Check Items Signatures. Please read
Pubsub Encryption for more details.
example¶
Create an item with a custom note XML:
$ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | li pubsub set -n "notes"
get¶
Retrieve items from specified node. Default output is prettified and highlighted XML.
If the node is end-to-end encrypted, items will be automatically and transparently
decrypted if the shared secrets are known. If you want to avoid this behaviour and get the
items undecrypted, you can use the --no-decrypt
flag.
example¶
Retrieve the last 5 notes from our custom notes node:
$ li pubsub get -n notes -M 5
delete¶
Delete an item from a node. If --no-notification
is specified, subscribers wont be notified
of the item retraction (this is NOT recommended, as it will cause trouble to keep items in
sync, take caution when using this flag).
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:
$ li 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.
draft commands can be used.
To publish an end-to-end encrypted item, you can use the -e, --encrypt
flag, and
share secrets with pubsub/secret: share, revoke or rotate node secrets. Please read
Pubsub Encryption for more details.
You can encrypt a single item to targeted entities with the --encrypt-for
flag (not
to be confused with --encrypt
which is used when a whole node is encrypted). Please
read Pubsub Encryption for more details.
To cryptographically sign an item, you can use the -X, --sign
flag (a mnemonic way
to remember the short option is to think of a cross made as a signature on a document).
Signature can then be checked with pubsub/signature: Sign and Check Items Signatures. Please read
Pubsub Encryption for more details.
example¶
Edit the last note in our custom node:
$ li pubsub edit -n notes -L
rename¶
Move a item to a new ID. As there is currently no “rename” or “move” operation in XMPP PubSub, this is done by republishing the item with the new ID, then deleting the old item if the publication succeed.
This is notably useful when user friendly URL based on ID are used, and one need to fix a typo or something else.
example¶
Rename a PubSub item with ID 123
to 456
:
$ li pubsub rename -n some_node -i 123 456
subscribe¶
Subscribe to a node.
Subscription is used to get notifications from the node in case of new/updated item or deletion.
If --public
is used, the subscription will be made visible to anybody. For this to
work, the target pubsub/PEP service must implement XEP-0465 Public Pubsub
Subscriptions. If your own server also implements XEP-0495 (and thus XEP-0376 Pubsub
Account Management wich is a dependency), your subscription will also be visible to
people requesting pubsub public subscriptions from your account.
Note
Making a subscription public is interesting to show your center of interests and to let other people discover people that you are subscribed to or who are subscribed to you (this correspond the the “following” and “followers” feature that is seen on some software).
However, it also makes your subscription visible to evil entities such as spammer, bot collectings informations for e.g. marketing or surveillance. In some locations, it may even be life threating as unwisely making public subscription may show your political views, sexual orientation, religion, etc.
Furthermore, if you make public subscriptions, your JID may be retrieved easily (public subscriptions can be checked to see if a JID exists and is used, or your JID can be simply found from subscribed node, or from your subscribers). This is often desirable in the case of social interactions, but this is to be known if you’re willing to keep your identifier secret (in this case, don’t use public subscriptions).
example¶
Subscribe to an information blog:
$ li pubsub subscribe -n informations -s pubsub.example.net
Pierre wants to subscribe to Louise blog, and to make it public, so other people can discover it:
$ li pubsub subscribe -n urn:xmpp:microblog:0 -s louise@example.org --public
unsubscribe¶
Unsubscribe from a node.
example¶
Unsubscribe from an information blog:
$ li pubsub unsubscribe -n informations -s pubsub.example.net
subscriptions¶
Retrieve subscriptions from a user, or subscriptions for all nodes on a service.
If no service and no node are specified, and if your server supports XEP-0376 Pubsub Account Management, all subscriptions to any server or node of the profile are returned.
-n NODE, --node NODE
can be used to request subscriptions for a specific node (e.g. if
it has subscription with multiple subIDs).
If --public
is used, only public subscriptions are retrieved. This can be used to find
public subscriptions from an external user. The PEP/Pubsub service of the target entity
must implement XEP-0465 Public Pubsub Subscriptions.
example¶
Pierre server supports XEP-0465. To check all the node where he has a subscription, Pierre can use this command:
$ li pubsub subscriptions
Retrieve all subscriptions on a specific pubsub service:
$ li pubsub subscriptions -s pubsub@example.net
Louise wants to checks to which node Pierre is publicly subscribed. She do it with following command:
$ li pubsub subscriptions --public -s pierre@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:
$ li pubsub affiliations -s pubsub@example.net
Retrieve affiliation for the notes
node:
$ li pubsub affiliations -s pubsub@example.net -n notes
reference¶
Send a reference (e.g. a mention) of a pubsub item to an entity.
example¶
Pierre send a reference to Louise to indicate that she has been mentioned in his blog post
with ID from-paris-to-noumea-abcd
:
$ li pubsub reference -s pierre@example.net -n urn:xmpp:microblog:0 -i from-paris-to-noumea-abcd louise@example.org
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, anditem_xml
which is the parsed XML as an lxmletree.Element
andetree
which is thelxml.etree
module.
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.
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 li command, or even an external tool.
The following actions are available:
print
(default)pretty print the found items.
exec
use the given li command on each found item. Everything after the
exec
is used to indicate the command and arguments to use (you must not specifyli
, 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:
$ li 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:
$ li 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 <title>
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:
$ li 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:
$ li 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.:
$ li 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):
$ li 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
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 ignoredthe 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 Libervia 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.
example¶
Imagine that you want to replace all occurrences of “SàT” by “Libervia” in your personal blog. You first create a Python script like this:
#!/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", "Libervia"))
And save it a some location, e.g. ~/expand_sat.py
(don’t forget to make it executable
with chmod +x ~/expand_sat.py
).
To be sure it’s safe, you can first do a dry-run and check the result:
$ li 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:
$ li 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:
$ li pubsub uri -n urn:xmpp:microblog:0
node¶
Subcommands for node management. Please check pubsub/node: PubSub nodes management.
attachments¶
Subcommands to add or remove data attached to pubsub items. Please check pubsub/attachments: (Un)Attach Metadata to Pubsub Items.
signature¶
Subcommands to handle items signature. Please check pubsub/signature: Sign and Check Items Signatures.
secret¶
Subcommands for pubsub node shared secrets management. Please check pubsub/secret: share, revoke or rotate node secrets.
hook¶
Subcommands for hooks management. Please check pubsub/hook: PubSub hooks management.
cache¶
Subcommands for cache management. Please check pubsub/cache: PubSub Cache Management.