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

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 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.