Mercurial > libervia-backend

comparison doc/libervia-cli/pubsub.rst @ 3771:e597dbfbc4c6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (cli/pubsub): document new `--public` flags: `--public` option is documented for `subscribe`, `subscriptions` and `node subscriptions get`, with examples. A warning has been added to show explicitely the privacy implication of using `--public` with `subscribe`. rel 365
author Goffi <goffi@goffi.org>
date Fri, 13 May 2022 19:32:06 +0200
parents 7bc443253b7c
children e183f1fbfa8d
comparison
equal deleted inserted replaced
3770:f31113777881 3771:e597dbfbc4c6
107 Subscribe to a node. 107 Subscribe to a node.
108 108
109 Subscription is used to get notifications from the node in case of new/updated item or 109 Subscription is used to get notifications from the node in case of new/updated item or
110 deletion. 110 deletion.
111 111
112 If ``--public`` is used, the subscription will be made visible to anybody. For this to
113 work, the target pubsub/PEP service must implement `XEP-0465 Public Pubsub
114 Subscriptions`_. If your own server also implements XEP-0495 (and thus `XEP-0376 Pubsub
115 Account Management`_ wich is a dependency), your subscription will also be visible to
116 people requesting pubsub public subscriptions from your account.
117
118 .. note::
119
120 Making a subscription public is interesting to show your center of interests and to let
121 other people discover people that you are subscribed to or who are subscribed to you
122 (this correspond the the "following" and "followers" feature that is seen on some
123 software).
124
125 However, it also makes your subscription visible to evil entities such as
126 spammer, bot collectings informations for e.g. marketing or surveillance. In some
127 locations, it may even be life threating as unwisely making public subscription may
128 show your political views, sexual orientation, religion, etc.
129
130 Furthermore, if you make public subscriptions, your JID may be retrieved easily (public
131 subscriptions can be checked to see if a JID exists and is used, or your JID can be
132 simply found from subscribed node, or from your subscribers). This is often desirable
133 in the case of social interactions, but this is to be known if you're willing to keep
134 your identifier secret (in this case, don't use public subscriptions).
135
136
112 example 137 example
113 ------- 138 -------
114 139
115 Subscribe to an information blog:: 140 Subscribe to an information blog::
116 141
117 $ li pubsub subscribe -n informations -s pubsub.example.net 142 $ li pubsub subscribe -n informations -s pubsub.example.net
143
144 Pierre wants to subscribe to Louise blog, and to make it public, so other people can
145 discover it::
146
147 $ li pubsub subscribe -n urn:xmpp:microblog:0 -s louise@example.org --public
118 148
119 unsubscribe 149 unsubscribe
120 =========== 150 ===========
121 151
122 Unsubscribe from a node. 152 Unsubscribe from a node.
129 $ li pubsub unsubscribe -n informations -s pubsub.example.net 159 $ li pubsub unsubscribe -n informations -s pubsub.example.net
130 160
131 subscriptions 161 subscriptions
132 ============= 162 =============
133 163
134 Retrieve subscriptions for all nodes on a service. 164 Retrieve subscriptions from a user, or subscriptions for all nodes on a service.
165
166 If no service and no node are specified, and if your server supports `XEP-0376 Pubsub
167 Account Management`_, all subscriptions to any server or node of the profile are returned.
135 168
136 ``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if 169 ``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if
137 it has subscription with multiple subIDs). 170 it has subscription with multiple subIDs).
138 171
139 example 172 If ``--public`` is used, only public subscriptions are retrieved. This can be used to find
140 ------- 173 public subscriptions from an external user. The PEP/Pubsub service of the target entity
141 174 must implement `XEP-0465 Public Pubsub Subscriptions`_.
142 Retrieve all subscriptions on a pubsub service:: 175
176 .. _XEP-0376 Pubsub Account Management: https://xmpp.org/extensions/xep-0376.html
177 .. _XEP-0465 Public Pubsub Subscriptions: https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
178
179
180 example
181 -------
182
183 Pierre server supports XEP-0465. To check all the node where he has a subscription, Pierre
184 can use this command::
185
186 $ li pubsub subscriptions
187
188 Retrieve all subscriptions on a specific pubsub service::
143 189
144 $ li pubsub subscriptions -s pubsub@example.net 190 $ li pubsub subscriptions -s pubsub@example.net
191
192 Louise wants to checks to which node Pierre is publicly subscribed. She do it with
193 following command::
194
195 $ li pubsub subscriptions --public -s pierre@example.net
145 196
146 affiliations 197 affiliations
147 ============= 198 =============
148 199
149 Retrieve affiliations for all nodes at a service. 200 Retrieve affiliations for all nodes at a service.