Mercurial > libervia-backend

comparison doc/jp/param.rst @ 3041:72583524cfd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (jp): jp commands are now fully documented: rel 232
author Goffi <goffi@goffi.org>
date Tue, 01 Oct 2019 22:49:06 +0200
parents
children
comparison
equal deleted inserted replaced
3040:fee60f17ebac 3041:72583524cfd3
1 ============================
2 param: manage SàT parameters
3 ============================
4
5 ``param`` commands allows to retrieve or set parameters as well as to export/import them
6 to a XML file.
7
8 Parameters are retrieve using a ``category`` and a ``name``, they are both case sensitive.
9
10 ``category`` is the name of the tabs that you see when you set parameters in a frontend
11 like Cagou or Libervia.
12
13 .. note::
14
15 You need to have your session started to retrieve of modify parameters. If you can't
16 or are not willing to connect for any reason (e.g. no internet connection), you can
17 use the ``--start-session`` option to start the profile session without connecting it
18 to the XMPP server.
19
20 get
21 ===
22
23 Retrieve list of categories, parameters or a specific parameter value:
24
25 - without argument, you'll get the list of categories
26 - with only a category specified, you'll get a list of parameters and their values
27 - with a category and a name, you'll get the value or requested attribute of the specified
28 parameters
29
30 By default you'll get the value of the parameters, but you can request an other attribute
31 (for instance its ``type`` or ``constraint``) using the ``-a ATTRIBUTE, --attribute
32 ATTRIBUTE`` argument.
33
34 You can set a security limit to retrieve only parameters allowed with this limit.
35 Security limit is an integer used in some frontends (like Libervia), to restrict
36 parameters modifiable by non privileged users. You can set it using ``--security-limit
37 SECURITY_LIMIT``, by default it is disabled (i.e. all parameters are returned).
38
39 examples
40 --------
41
42 Get list of categories::
43
44 $ jp param get
45
46 Get list of parameters in ``General`` category::
47
48 $ jp param get General
49
50 Get JID set for default profile. It is set in ``Connection`` category, with the parameters
51 named ``JabberID`` (be careful with the case)::
52
53 $ jp param get Connection JabberID
54
55 Get the type of the ``check_certificate`` parameters in ``Connection`` category::
56
57 $ jp param get Connection check_certificate -a type
58
59 Get the constraint of the ``Priority`` parameters in ``Connection`` category::
60
61 $ jp param get Connection Priority -a constraint
62
63 set
64 ===
65
66 As expected, this command set a SàT parameter. The ``category``, ``name`` and ``value``
67 are needed as positional arguments.
68
69 ``--security-limit SECURITY_LIMIT`` can be used if you want an update to be rejected if
70 the parameter is not modifiable with this limit. This can be useful if you use ``jp`` from
71 an external tool and you want to limit damage risks, or for testing purpose.
72
73 examples
74 --------
75
76 Use Markdown_ syntax for composition (e.g. for editing blog posts)::
77
78 $ jp param set Composition Syntax markdown
79
80 Try to change jid of the profile with a low security limit, this command should fail::
81
82 $ jp param set --security-limit 0 Connection JabberID some_random_jid@example.org
83
84 .. _Markdown: https://daringfireball.net/projects/markdown/
85
86 .. _jp-param_save:
87
88 save
89 ====
90
91 Save the parameters structure to an external files. The parameters are saved as XML. The only
92 expected argument is the path to the destination file.
93
94 .. note::
95
96 it's the parameters structure and not the parameters values which are saved. This is
97 low level method and most end users won't probably need it
98
99 example
100 -------
101
102 Save parameters structure to ``~/parameters.xml``::
103
104 $ jp param save ~/parameters.xml
105
106 .. _jp-param_load:
107
108 load
109 ====
110
111 Load and merge the parameters structure from external XML files. The only expected
112 argument is the path to the source file.
113
114 .. note::
115
116 it's the parameters structure and not the parameters values which is loaded and merged.
117 This is low level method and most end users won't probably need it
118
119 example
120 -------
121
122 Load and merge parameters structure from ``~/parameters.xml``::
123
124 $ jp param load ~/parameters.xml