Mercurial > hg > orthanc-book
comparison Sphinx/source/users/webdav.rst @ 526:e9d8c7e5afbd
webdav
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 16 Oct 2020 10:53:56 +0200 |
parents | |
children | 44e9db538cd9 |
comparison
equal
deleted
inserted
replaced
525:f364b00bf02c | 526:e9d8c7e5afbd |
---|---|
1 .. _webdav: | |
2 | |
3 Accessing Orthanc from the file explorer using WebDAV | |
4 ===================================================== | |
5 | |
6 .. contents:: | |
7 | |
8 Since release 1.8.0, the content of an Orthanc server can be | |
9 **mapped/mounted as a network share** thanks to `WebDAV | |
10 <https://en.wikipedia.org/wiki/WebDAV>`__. Thanks to this feature, you | |
11 can easily browse the DICOM instances that are stored by Orthanc using | |
12 the built-in file explorer of your operating system. It is possible to | |
13 download, upload or delete DICOM instances as well. | |
14 | |
15 Orthanc creates a so-called **virtual filesystem** that indexes the | |
16 same DICOM resources according to different views (data can be | |
17 accessed by patients, by studies, by date, or by DICOM UIDs). | |
18 | |
19 | |
20 .. _webdav_screenshots: | |
21 | |
22 Screenshots | |
23 ----------- | |
24 | |
25 The screenshots below are generated using the `test virtual machines | |
26 <https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/>`__ | |
27 that are provided by Microsoft. | |
28 | |
29 Here is the layout of the WebDAV server of Orthanc 1.8.0: | |
30 | |
31 .. image:: ../images/webdav-win7-sample.png | |
32 :align: center | |
33 :width: 512 | |
34 | |
35 As can be noticed, Orthanc exposes a full hierarchy of DICOM | |
36 resources. These resources are transparently mapped to the database of | |
37 Orthanc. The same resource will appear at multiple locations of this | |
38 virtual filesystem, but in practice, it is stored only once. One can | |
39 choose the best way to access the information depending on the use | |
40 case. | |
41 | |
42 Uploading a full folder containing a DICOM study (such as a CD or a | |
43 DVD containing a DICOMDIR) is as simple as a drag-and-drop onto the | |
44 ``/uploads/`` folder: | |
45 | |
46 .. image:: ../images/webdav-win7-upload.png | |
47 :align: center | |
48 :width: 512 | |
49 | |
50 | |
51 Server configuration | |
52 -------------------- | |
53 | |
54 Options | |
55 ^^^^^^^ | |
56 | |
57 Three configuration options can be used to configure the WebDAV | |
58 server: | |
59 | |
60 * ``WebDavEnabled`` to enable/disable WebDAV. | |
61 | |
62 * ``WebDavDeleteAllowed`` to turn on/off the possibility of deleting | |
63 DICOM resources using WebDAV. This can be disabled for security | |
64 reasons. | |
65 | |
66 * ``WebDavUploadAllowed`` to turn on/off the possibility of uploading | |
67 DICOM resources using WebDAV. | |
68 | |
69 | |
70 Security | |
71 ^^^^^^^^ | |
72 | |
73 As WebDAV is an application layer above HTTP, you should pay attention | |
74 to :ref:`protect your HTTP server <security_http>`. At the minimum, | |
75 you should enable HTTP Basic Authentication (check out configuration | |
76 option ``RegisteredUsers``). The client will have to provide her | |
77 credentials when mapping the WebDAV share. | |
78 | |
79 If you want to control which user can see which resource, you should | |
80 protect your network share by creating **access control lists** | |
81 through a :ref:`Lua script <lua-filter-rest>`, through the | |
82 :ref:`advanced authorization plugin <authorization>`, or through | |
83 :ref:`your own plugin <creating-plugins>` | |
84 (cf. ``OrthancPluginRegisterIncomingHttpRequestFilter2()``). | |
85 | |
86 The HTTP methods that are used by WebDAV are ``GET`` (for read-only | |
87 accesses), ``PUT`` (for uploads), and ``DELETE`` (for deletions). The | |
88 access control lists can be focused on these methods. | |
89 | |
90 Finally, it is highly recommended to enable :ref:`HTTPS encryption | |
91 <https>`, which might need additional configuration on some operating | |
92 systems (see below for Microsoft Windows 10). | |
93 | |
94 | |
95 Client configuration | |
96 -------------------- | |
97 | |
98 Nautilus on Ubuntu 18.04 | |
99 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
100 | |
101 It is quite straightforward to use the WebDAV server using Nautilus on | |
102 Ubuntu: | |
103 | |
104 .. image:: ../images/webdav-nautilus-1.png | |
105 :align: center | |
106 :width: 512 | |
107 | |
108 Obviously, adapt the IP address and HTTP port number to your setup. | |
109 Once the share is connected, it is readily accessible: | |
110 | |
111 .. image:: ../images/webdav-nautilus-2.png | |
112 :align: center | |
113 :width: 512 | |
114 | |
115 **Important:** If you use :ref:`HTTPS encryption <https>`, which is | |
116 recommended for security reasons, replace the prefix ``dav://`` by | |
117 ``davs://``. | |
118 | |
119 | |
120 Microsoft Windows 7 | |
121 ^^^^^^^^^^^^^^^^^^^ | |
122 | |
123 This section illustrates how to use WebDAV on a Microsoft Windows 7 | |
124 operating system. Obviously, the procedure is very similar for more | |
125 recent versions of Microsoft Windows, and many tutorials are available | |
126 on Internet. | |
127 | |
128 WebDAV has a `known performance issue | |
129 <https://oddballupdate.com/2009/12/fix-slow-webdav-performance-in-windows-7/>`__ | |
130 on barebone Microsoft Windows 7. To fix this issue, first open the | |
131 "Internet Properties" configuration panel: | |
132 | |
133 .. image:: ../images/webdav-win7-config5.png | |
134 :align: center | |
135 :width: 512 | |
136 | |
137 Then simply uncheck the "Automatically detect settings" checkbox in | |
138 the "LAN settings" panel: | |
139 | |
140 .. image:: ../images/webdav-win7-config6.png | |
141 :align: center | |
142 :width: 384 | |
143 | |
144 Once this is done, in order to map Orthanc as a network share on | |
145 Microsoft Windows 7, first open the File Explorer, and right-click on | |
146 "Computer": | |
147 | |
148 .. image:: ../images/webdav-win7-config1.png | |
149 :align: center | |
150 :width: 512 | |
151 | |
152 This will open the "Add Network Location Wizard". Click on "Next" to | |
153 choose the (only) available option: | |
154 | |
155 .. image:: ../images/webdav-win7-config2.png | |
156 :align: center | |
157 :width: 384 | |
158 | |
159 Now enter the IP address and the HTTP port of your Orthanc server, and | |
160 don't forget to add the ``/webdav/`` suffix: | |
161 | |
162 .. image:: ../images/webdav-win7-config3.png | |
163 :align: center | |
164 :width: 384 | |
165 | |
166 Give a name to your network share: | |
167 | |
168 .. image:: ../images/webdav-win7-config4.png | |
169 :align: center | |
170 :width: 384 | |
171 | |
172 At the "Completing the Add Network Location Wizard", click on | |
173 "Finish". You'll then be able to use the network share as depicted in | |
174 the :ref:`screenshots above <webdav_screenshots>`. | |
175 | |
176 **Important:** For some reason, Microsoft Windows 7 sometimes "`gets | |
177 lost | |
178 <https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/cannot-automatically-reconnect-dav-share>`__" | |
179 after an upload and cannot access Orthanc anymore. In such situations, | |
180 you'll have to delete the network share and repeat the steps above | |
181 again. | |
182 | |
183 | |
184 Remote access using Microsoft Windows 10 | |
185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
186 | |
187 Depending on your security settings, `Microsoft Windows 10 might impose | |
188 the use of HTTPS <>`__ in the Orthanc server. First, you must obviously | |
189 configure :ref:`HTTPS security in Orthanc <https>`. | |
190 | |
191 In order to connect successfully to Orthanc WebDAV server using basic | |
192 authentication and SSL with self-signed certificate. | |
193 | |
194 1) download the ``.pem`` certificate | |
195 | |
196 2) Open "Control Panel" → "Manage Computer Certificates" | |
197 | |
198 3) Right click on "Certificates - Local Computer → Trusted Root | |
199 Certification Authorities → Certificates" and choose "All Tasks → | |
200 Import..." | |
201 | |
202 4) Select the ``.pem`` certificate (you might need to enforce | |
203 displaying ``*.*`` files in the dialog box, for the ``.pem`` | |
204 extension is not part of the standard certificate extensions) | |
205 | |
206 5) Choose "Place all certifications in the following store: Trusted | |
207 Root Certification Authorities" | |
208 | |
209 6) A dialog box should pop up with "The import was successful" | |
210 | |
211 When done, you can test the WebDAV connection : | |
212 | |
213 1) Right click on the Explorer namespace root ("This PC", in Windows 10) | |
214 | |
215 2) Choose "Map Network Drive" | |
216 | |
217 3) Click the link named "Connect to a Web site that you can use..." | |
218 | |
219 4) Choose custom network location | |
220 | |
221 5) Type the WebDAV address like: ``http://10.10.10.107:8042/webdav/`` | |
222 | |
223 6) If all goes well, you should be prompted for the basic auth credentials. | |
224 | |
225 When this is done, the WebDAV location should be mounted at the top of | |
226 the Explorer namespace (next to the C: drive, etc...). Something to | |
227 try if the mount fails: | |
228 | |
229 - open ``regedit.exe`` | |
230 | |
231 - open the ``HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters key`` | |
232 | |
233 - create the ``BasicAuthLevel`` DWORD value if needed | |
234 | |
235 - set the ``BasicAuthLevel`` DWORD value to ``2`` | |
236 | |
237 This should *not* be required, but was enabled on the PC that was used | |
238 to test the mounting procedure. `Details here | |
239 <http://techgenix.com/EnableBasicAuthforWebDAVonWindows7/>`__ | |
240 | |
241 | |
242 | |
243 Debugging WebDAV | |
244 ---------------- | |
245 | |
246 As of release 1.8.0, the WebDAV server of Orthanc has been tested | |
247 against the following WebDAV clients: Nautilus, `davfs2 | |
248 <https://en.wikipedia.org/wiki/Davfs2>`__, Microsoft Windows XP, | |
249 Microsoft Windows 7, and Microsoft Windows 10. | |
250 | |
251 It is obviously impossible for us to test against all the possible | |
252 platforms. If you encounter an issue using your WebDAV client, you | |
253 should send us a trace generated by the `wsgidav reference server | |
254 <https://github.com/mar10/wsgidav/>`__ so that we can identify what is | |
255 the non-respect of Orthanc wrt. the WebDAV standard. | |
256 | |
257 .. highlight:: bash | |
258 | |
259 On Ubuntu, here are the commands to generate a useful log:: | |
260 | |
261 $ sudo pip install wsgidav cheroot | |
262 $ mkdir -p /tmp/webdav/hello | |
263 $ echo "foo" > /tmp/webdav/hello/world | |
264 $ wsgidav -v -v --auth anonymous --host=0.0.0.0 --port=8042 --root=/tmp/webdav/ | tee /tmp/wsgidav.log | |
265 | |
266 Connect your WebDAV client to ``http://localhost:8042/``, and do some | |
267 basic operations (access ``/hello/world``, create a file, create a | |
268 folder, and delete a file). Then, stop the ``wsgidav`` server and | |
269 publish the content of the ``/tmp/wsgidav.log`` logfile on the | |
270 `Orthanc Users discussion group | |
271 <https://groups.google.com/g/orthanc-users>`__. |