Mercurial > libervia-backend

comparison doc/libervia-cli/profile.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/profile.rst@d6f903c59a56
children cc3d00d07c34
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 =============================
2 profile: SàT profile handling
3 =============================
4
5 Profiles are the names associated with accounts in SàT, for more informations you can
6 check :ref:`glossary`. The `profile` commands help you create/delete/modify and manage
7 profiles.
8
9
10 connect
11 =======
12
13 Unsurprisingly this command connects your profile, i.e. log-in your XMPP account. This
14 command uses :ref:`libervia-cli_common_profile` common commands, so you can use either ``-c,
15 --connect`` to connect to XMPP server, or ``--start-session`` if you want to start SàT
16 profile session without connecting to XMPP server (for instance if you want to modify
17 parameters without connecting to XMPP server).
18
19 Note that :ref:`libervia-cli_common_profile` common commands are available in commands needing a
20 connected profile, ``li profile connect`` is interesting if you only want to connect your
21 profile/start a session.
22
23 example
24 -------
25
26 Connect the default profile::
27
28 $ li profile connect -c
29
30
31 disconnect
32 ==========
33
34 Disconnect your profile from XMPP server. There is no option beside the
35 :ref:`libervia-cli_common_profile` common options.
36
37 example
38 -------
39
40 Disconnect the profile ``pierre``::
41
42 $ li profile disconnect -p pierre
43
44
45 create
46 ======
47
48 Create a new SàT profile. The only mandatory argument is the profile name, but you'll
49 probably want to associate an XMPP jid with ``-j JID, --jid JID`` and a profile password
50 with ``-p PASSWORD, --password PASSWORD``. By default, profile password will be used for
51 XMPP password (see note below), but you may specify XMPP password with ``-x PASSWORD,
52 --xmpp-password PASSWORD``.
53
54 SàT is also capable to manage components, which can be seen as XMPP server independent
55 plugins. To create a component profile, you'll have to use ``-C COMPONENT, --component
56 COMPONENT`` where ``COMPONENT`` is the component entry point (check the documentation of
57 the component that you want to use to get its entry point).
58
59 If you want a profile to connect automatically on backend startup (notably useful for
60 components), you can use the ``-A [{true,false}], --autoconnect [{true,false}]`` argument.
61
62 .. note::
63
64 profile password and XMPP password are not the same: the profile password is the
65 password of your SàT profile, while the XMPP password is the one checked by your XMPP
66 server. If specify a jid with ``--jid`` and you don't specify an XMPP password, the
67 profile password will be used by default.
68
69 The reason to have distinct password is that you may use a different password for
70 profile, including an empty one if you want SàT to connect your profile without
71 having to enter a password. Also the XMPP password is encrypted in database using the
72 profile password (which is not stored in database, only a hash is kept).
73
74
75 .. note::
76
77 passwords in li are currently specified directly on the command-line and not prompted,
78 this is not safe from a security point of view as people can see it on the screen, it
79 may stay in your shell history, or visible on process list. Keep that in mind if you're
80 in a public environment or on a public machine. This will be improved for SàT 0.8.
81
82 examples
83 --------
84
85 Nestor wants to create a profile for its account on ``example.org``, he specifies a
86 profile password only, so it will also be used as the XMPP password::
87
88 $ li profile create nestor -j nestor@example.org -p some_password
89
90 Create a component profile for the file sharing component (whose entry point is
91 ``file_sharing``). The jid of the service is specified with ``--jid`` (note that we don't
92 use a node as it is a jid of a component) and the ``--xmpp-password`` is the shared
93 secret. Here the profile password is kept empty to not have to enter manually the XMPP
94 password each time we connect the service::
95
96 $ li profile create file_sharing -j files.example.org -p "" --xmpp-password
97 some_shared_secret -C file_sharing
98
99
100 default
101 =======
102
103 This command simply prints the default profile (i.e. the profile used when none is
104 specified with ``-p PROFILE, --profile PROFILE``). The default profile is either the first
105 one that you've created, or the one you have explicitly set as default.
106
107 example
108 -------
109
110 Print default profile::
111
112 $ li profile default
113
114
115 delete
116 ======
117
118 Delete a profile and all its associated data. This delete the SàT profile and associated
119 data (i.e. local data), but doesn't request the XMPP server to delete anything.
120
121 By default a confirmation is requested, use ``-f, --force`` to avoid it (be cautious with
122 this option).
123
124 example
125 -------
126
127 Delete the profile of Pierre::
128
129 $ li profile delete pierre
130
131
132 info
133 ====
134
135 Display information on a profile. For now, only the registered jid is shown, and
136 optionally the XMPP password. To display the XMPP password, use ``--show-password`` but be
137 careful that nobody can see your screen, as **this password will be shown in clear text**.
138
139 example
140 -------
141
142 Show jid and XMPP password for default profile::
143
144 $ li profile info --show-password
145
146
147 list
148 ====
149
150 Show all profiles. You can use ``-c, --clients`` to show only client profiles, and ``-C,
151 --components`` to show only component profiles.
152
153 example
154 -------
155
156 Show all profiles::
157
158 $ li profile list
159
160
161 modify
162 ======
163
164 Update an existing profile. You can use this command to change profile password (with ``-w
165 PASSWORD, --password PASSWORD``) or even disable it (with ``--disable-password``, this is
166 equivalent to using an empty profile password ; be cautious with this option, see the note
167 below).
168
169 With ``-j JID, --jid JID`` and ``-x PASSWORD, --xmpp-password PASSWORD`` you can change
170 XMPP jid and password.
171
172 This command can also be used to select the default password, use the ``-D, --default``
173 flag for that.
174
175 .. note::
176
177 Be cautious with ``--disable-password`` that means that no password will be needed with
178 any frontend of SàT to use this profile, and that XMPP password will be easy to
179 retrieve for anybody having an access to the machine where SàT is installed
180
181 examples
182 --------
183
184 Pierre has changed server, he can update his jid and password like this::
185
186 $ li profile modify -p pierre -j pierre@example.org -x new_password
187
188 Use ``louise`` as default profile::
189
190 $ li profile modify -p louise -D
191
192 Disable profile password for default profile (be cautious, see the note above)::
193
194 $ li profile modify --disable-password