Mercurial > p > roundup > code

comparison doc/xmlrpc.txt @ 7472:db58a86aa29d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Redo headers. Elevete lack of ssl to caution.
author John Rouillard <rouilj@ieee.org>
date Thu, 08 Jun 2023 09:01:17 -0400
parents e7b4ad2c57ac
children 924b07252412
comparison
equal deleted inserted replaced
7471:a4987f5ebee0 7472:db58a86aa29d
12 12
13 .. contents:: 13 .. contents::
14 :local: 14 :local:
15 15
16 Introduction 16 Introduction
17 ------------ 17 ============
18
18 Version 1.4 of Roundup includes an XML-RPC frontend for remote access. The 19 Version 1.4 of Roundup includes an XML-RPC frontend for remote access. The
19 XML-RPC interface allows a limited subset of commands similar to those found in 20 XML-RPC interface allows a limited subset of commands similar to those found in
20 local `roundup-admin` tool. 21 local `roundup-admin` tool.
21 22
22 By default XML-RPC is accessible from ``/xmlrpc`` endpoint: 23 By default XML-RPC is accessible from ``/xmlrpc`` endpoint:
25 26
26 For demo tracker the URL would be: 27 For demo tracker the URL would be:
27 28
28 http://localhost:8917/demo/xmlrpc 29 http://localhost:8917/demo/xmlrpc
29 30
30 Enabling XML-RPC server 31 Enabling XML-RPC
31 ----------------------- 32 ================
32 There are two ways to run the XML-RPC interface: 33 There are two ways to run the XML-RPC interface:
33 34
34 through roundup itself 35 through roundup itself
35 36
36 stand alone roundup-xmlrpc-server 37 stand alone roundup-xmlrpc-server
37 38
38 39
39 through roundup 40 Through Roundup
40 --------------- 41 ---------------
42
41 The XML-RPC service is available from the roundup HTTP server under 43 The XML-RPC service is available from the roundup HTTP server under
42 /xmlrpc. 44 /xmlrpc.
43 45
44 To enable this set ``enable_xmlrpc`` to ``yes`` in the ``[web]`` 46 To enable this set ``enable_xmlrpc`` to ``yes`` in the ``[web]``
45 section of the ``config.ini`` file in your tracker. 47 section of the ``config.ini`` file in your tracker.
51 db.security.addPermissionToRole('User', 'Xmlrpc Access') 53 db.security.addPermissionToRole('User', 'Xmlrpc Access')
52 54
53 This is usually included near where other permissions like "Web Access" 55 This is usually included near where other permissions like "Web Access"
54 or "Email Access" are assigned. 56 or "Email Access" are assigned.
55 57
56 stand alone roundup-xmlrpc-server 58 Standalone roundup-xmlrpc-server
57 --------------------------------- 59 --------------------------------
58 Using roundup to access the xmlrpc interface is preferred. Roundup 60
61 Using Roundup to access the xmlrpc interface is preferred. Roundup
59 provides better control over who can use the interface. 62 provides better control over who can use the interface.
60 63
61 The Roundup XML-RPC standalone server must be started before remote 64 The Roundup XML-RPC standalone server must be started before remote
62 clients can access the tracker via XML-RPC. ``roundup-xmlrpc-server`` 65 clients can access the tracker via XML-RPC. ``roundup-xmlrpc-server``
63 is installed in the scripts directory alongside ``roundup-server`` and 66 is installed in the scripts directory alongside ``roundup-server`` and
67 roundup-xmlrpc-server -i ``/path/to/tracker`` 70 roundup-xmlrpc-server -i ``/path/to/tracker``
68 71
69 The default port is ``8000``. An alternative port can be specified with the 72 The default port is ``8000``. An alternative port can be specified with the
70 ``--port`` switch. 73 ``--port`` switch.
71 74
72 security consideration 75 Security Consideration
73 ---------------------- 76 ======================
77
74 Both the standalone and embedded roundup XML endpoints used the 78 Both the standalone and embedded roundup XML endpoints used the
75 default python XML parser. This parser is know to have security 79 default python XML parser. This parser is know to have security
76 issues. For details see: https://pypi.org/project/defusedxml/. 80 issues. For details see: https://pypi.org/project/defusedxml/.
77 You may wish to use the rest interface which doesn't have the same 81 You may wish to use the rest interface which doesn't have the same
78 issues. Patches with tests to roundup to use defusedxml are welcome. 82 issues. Patches with tests to roundup to use defusedxml are welcome.
79 83
80 Note that the current ``roundup-xmlrpc-server`` implementation does 84 .. caution::
81 not support SSL. This means that usernames and passwords will be 85
82 passed in cleartext unless the server is being proxied behind another 86 The current ``roundup-xmlrpc-server`` implementation does not support
83 server (such as Apache or lighttpd) that provide SSL. 87 SSL. This means that usernames and passwords will be passed in
88 cleartext unless the server is being proxied behind another server
89 (such as Apache or lighttpd) that provide SSL.
84 90
85 Client API 91 Client API
86 ---------- 92 ==========
87 The server currently implements seven methods/commands. Each method 93 The server currently implements seven methods/commands. Each method
88 requires that the user provide a username and password in the HTTP 94 requires that the user provide a username and password in the HTTP
89 authorization header in order to authenticate the request against the 95 authorization header in order to authenticate the request against the
90 tracker. 96 tracker.
91 97
135 instantiating the ServerProxy). The ``attributes`` are given as a 141 instantiating the ServerProxy). The ``attributes`` are given as a
136 dictionary of name value pairs to search for. See also 142 dictionary of name value pairs to search for. See also
137 :ref:`query-tracker`. 143 :ref:`query-tracker`.
138 ======= ==================================================================== 144 ======= ====================================================================
139 145
140 sample python client 146 Sample Python Client
141 ==================== 147 ====================
142 148
143 This client will work if you turn off the x-requested-with header and 149 This client will work if you turn off the x-requested-with header and
144 the only CSRF header check you require is the HTTP host header:: 150 the only CSRF header check you require is the HTTP host header::
145 151
169 >>> roundup_server.filter('user',[],{'username':'adm'}) 175 >>> roundup_server.filter('user',[],{'username':'adm'})
170 [] 176 []
171 >>> roundup_server.lookup('user','admin') 177 >>> roundup_server.lookup('user','admin')
172 '1' 178 '1'
173 179
174 advanced python client adding anti-csrf headers 180 Advanced Python Client Adding anti-csrf Headers
175 =============================================== 181 ===============================================
176 182
177 The one below adds Referer and X-Requested-With headers so it can pass 183 The one below adds Referer and X-Requested-With headers so it can pass
178 stronger CSRF detection methods. It also generates a fault message 184 stronger CSRF detection methods. It also generates a fault message
179 from the server and reports it. Note if you are using http rather than 185 from the server and reports it. Note if you are using http rather than
Roundup Issue Tracker: http://roundup-tracker.org/