Mercurial > hg > orthanc-book
annotate Sphinx/source/users/webdav.rst @ 561:e5ca21b61fe1
PostgreSQL 3.3
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Mon, 14 Dec 2020 18:08:16 +0100 |
parents | 8e27dbf6f39e |
children | dda28dfd7d9d |
rev | line source |
---|---|
526 | 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 | |
529 | 50 As soon as the DICOM files have been dragged-and-dropped, they are |
51 progressively ingested by Orthanc. Once a DICOM file has been | |
52 ingested, it is automatically removed from the ``/uploads/`` folder. | |
53 | |
54 Note that it is not possible to rename any file, as this is a virtual | |
55 filesystem that is permanently and transparently reconstructed out of | |
56 the content of the Orthanc database. | |
57 | |
526 | 58 |
59 Server configuration | |
60 -------------------- | |
61 | |
62 Options | |
63 ^^^^^^^ | |
64 | |
65 Three configuration options can be used to configure the WebDAV | |
66 server: | |
67 | |
68 * ``WebDavEnabled`` to enable/disable WebDAV. | |
69 | |
70 * ``WebDavDeleteAllowed`` to turn on/off the possibility of deleting | |
71 DICOM resources using WebDAV. This can be disabled for security | |
72 reasons. | |
73 | |
74 * ``WebDavUploadAllowed`` to turn on/off the possibility of uploading | |
75 DICOM resources using WebDAV. | |
76 | |
77 | |
78 Security | |
79 ^^^^^^^^ | |
80 | |
81 As WebDAV is an application layer above HTTP, you should pay attention | |
82 to :ref:`protect your HTTP server <security_http>`. At the minimum, | |
83 you should enable HTTP Basic Authentication (check out configuration | |
84 option ``RegisteredUsers``). The client will have to provide her | |
85 credentials when mapping the WebDAV share. | |
86 | |
87 If you want to control which user can see which resource, you should | |
88 protect your network share by creating **access control lists** | |
89 through a :ref:`Lua script <lua-filter-rest>`, through the | |
90 :ref:`advanced authorization plugin <authorization>`, or through | |
91 :ref:`your own plugin <creating-plugins>` | |
92 (cf. ``OrthancPluginRegisterIncomingHttpRequestFilter2()``). | |
93 | |
94 The HTTP methods that are used by WebDAV are ``GET`` (for read-only | |
95 accesses), ``PUT`` (for uploads), and ``DELETE`` (for deletions). The | |
96 access control lists can be focused on these methods. | |
97 | |
98 Finally, it is highly recommended to enable :ref:`HTTPS encryption | |
99 <https>`, which might need additional configuration on some operating | |
100 systems (see below for Microsoft Windows 10). | |
101 | |
102 | |
103 Client configuration | |
104 -------------------- | |
105 | |
106 Nautilus on Ubuntu 18.04 | |
107 ^^^^^^^^^^^^^^^^^^^^^^^^ | |
108 | |
109 It is quite straightforward to use the WebDAV server using Nautilus on | |
110 Ubuntu: | |
111 | |
112 .. image:: ../images/webdav-nautilus-1.png | |
113 :align: center | |
114 :width: 512 | |
115 | |
116 Obviously, adapt the IP address and HTTP port number to your setup. | |
117 Once the share is connected, it is readily accessible: | |
118 | |
119 .. image:: ../images/webdav-nautilus-2.png | |
120 :align: center | |
121 :width: 512 | |
122 | |
123 **Important:** If you use :ref:`HTTPS encryption <https>`, which is | |
124 recommended for security reasons, replace the prefix ``dav://`` by | |
125 ``davs://``. | |
126 | |
127 | |
128 Microsoft Windows 7 | |
129 ^^^^^^^^^^^^^^^^^^^ | |
130 | |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
131 First of all, make sure to adapt the value of the registry key |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
132 ``BasicAuthLevel``, :ref:`as explained below <webdav_windows_fix>`. |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
133 Otherwise, you might not be able to connect. |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
134 |
526 | 135 This section illustrates how to use WebDAV on a Microsoft Windows 7 |
136 operating system. Obviously, the procedure is very similar for more | |
137 recent versions of Microsoft Windows, and many tutorials are available | |
138 on Internet. | |
139 | |
140 WebDAV has a `known performance issue | |
141 <https://oddballupdate.com/2009/12/fix-slow-webdav-performance-in-windows-7/>`__ | |
142 on barebone Microsoft Windows 7. To fix this issue, first open the | |
143 "Internet Properties" configuration panel: | |
144 | |
145 .. image:: ../images/webdav-win7-config5.png | |
146 :align: center | |
147 :width: 512 | |
148 | |
149 Then simply uncheck the "Automatically detect settings" checkbox in | |
150 the "LAN settings" panel: | |
151 | |
152 .. image:: ../images/webdav-win7-config6.png | |
153 :align: center | |
154 :width: 384 | |
155 | |
156 Once this is done, in order to map Orthanc as a network share on | |
157 Microsoft Windows 7, first open the File Explorer, and right-click on | |
158 "Computer": | |
159 | |
160 .. image:: ../images/webdav-win7-config1.png | |
161 :align: center | |
162 :width: 512 | |
163 | |
164 This will open the "Add Network Location Wizard". Click on "Next" to | |
165 choose the (only) available option: | |
166 | |
167 .. image:: ../images/webdav-win7-config2.png | |
168 :align: center | |
169 :width: 384 | |
170 | |
171 Now enter the IP address and the HTTP port of your Orthanc server, and | |
172 don't forget to add the ``/webdav/`` suffix: | |
173 | |
174 .. image:: ../images/webdav-win7-config3.png | |
175 :align: center | |
176 :width: 384 | |
177 | |
178 Give a name to your network share: | |
179 | |
180 .. image:: ../images/webdav-win7-config4.png | |
181 :align: center | |
182 :width: 384 | |
183 | |
184 At the "Completing the Add Network Location Wizard", click on | |
185 "Finish". You'll then be able to use the network share as depicted in | |
186 the :ref:`screenshots above <webdav_screenshots>`. | |
187 | |
188 **Important:** For some reason, Microsoft Windows 7 sometimes "`gets | |
189 lost | |
190 <https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/cannot-automatically-reconnect-dav-share>`__" | |
191 after an upload and cannot access Orthanc anymore. In such situations, | |
192 you'll have to delete the network share and repeat the steps above | |
193 again. | |
194 | |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
195 Note that you can find additional information `in the thread about |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
196 WebDAV on the discussion forum |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
197 <https://groups.google.com/g/orthanc-users/c/Iq-Ftv5xGjA/m/68kNcbanAgAJ>`__. |
526 | 198 |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
199 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
200 Secure access using Microsoft Windows 10 |
526 | 201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
202 | |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
203 First of all, make sure to adapt the value of the registry key |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
204 ``BasicAuthLevel``, :ref:`as explained below <webdav_windows_fix>`. |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
205 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
206 Depending on your security settings, Microsoft Windows 10 might also |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
207 impose the use of HTTPS in the Orthanc server. First, you must |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
208 obviously configure :ref:`HTTPS security in Orthanc <https>`. |
526 | 209 |
210 In order to connect successfully to Orthanc WebDAV server using basic | |
211 authentication and SSL with self-signed certificate. | |
212 | |
213 1) download the ``.pem`` certificate | |
214 | |
215 2) Open "Control Panel" → "Manage Computer Certificates" | |
216 | |
217 3) Right click on "Certificates - Local Computer → Trusted Root | |
218 Certification Authorities → Certificates" and choose "All Tasks → | |
219 Import..." | |
220 | |
221 4) Select the ``.pem`` certificate (you might need to enforce | |
222 displaying ``*.*`` files in the dialog box, for the ``.pem`` | |
223 extension is not part of the standard certificate extensions) | |
224 | |
225 5) Choose "Place all certifications in the following store: Trusted | |
226 Root Certification Authorities" | |
227 | |
228 6) A dialog box should pop up with "The import was successful" | |
229 | |
230 When done, you can test the WebDAV connection : | |
231 | |
232 1) Right click on the Explorer namespace root ("This PC", in Windows 10) | |
233 | |
234 2) Choose "Map Network Drive" | |
235 | |
236 3) Click the link named "Connect to a Web site that you can use..." | |
237 | |
238 4) Choose custom network location | |
239 | |
529 | 240 5) Type the WebDAV address like: ``https://10.10.10.107:8042/webdav/`` |
526 | 241 |
242 6) If all goes well, you should be prompted for the basic auth credentials. | |
243 | |
244 When this is done, the WebDAV location should be mounted at the top of | |
245 the Explorer namespace (next to the C: drive, etc...). Something to | |
246 try if the mount fails: | |
247 | |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
248 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
249 Tips for other operating systems |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
250 -------------------------------- |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
251 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
252 .. _webdav_windows_fix: |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
253 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
254 Microsoft Windows 7, 8.x or 10 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
255 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
256 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
257 If you cannot access WebDAV from Microsoft Windows (with version above |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
258 7), as a first step, change the value of the registry key |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
259 ``BasicAuthLevel`` within the system registry to value ``2`` (by |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
260 default, it comes with value ``1`` that prevents WebDAV access). Here |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
261 are the steps: |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
262 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
263 - Open ``regedit.exe`` |
526 | 264 |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
265 - Open the ``HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`` key |
526 | 266 |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
267 - Create the ``BasicAuthLevel`` DWORD value if needed |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
268 |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
269 - Set the ``BasicAuthLevel`` DWORD value to ``2`` |
526 | 270 |
271 This should *not* be required, but was enabled on the PC that was used | |
272 to test the mounting procedure. `Details here | |
273 <http://techgenix.com/EnableBasicAuthforWebDAVonWindows7/>`__ | |
274 | |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
275 Note that you can find additional information `in the thread about |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
276 WebDAV on the discussion forum |
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
277 <https://groups.google.com/g/orthanc-users/c/Iq-Ftv5xGjA/m/68kNcbanAgAJ>`__. |
526 | 278 |
534
8e27dbf6f39e
BasicAuthLevel put in more visible way
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
530
diff
changeset
|
279 |
530
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
280 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
281 Microsoft Windows Server 2012 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
282 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
283 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
284 1. **Install Desktop Experience**: Server manager > Add Features > |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
285 User Interfaces and Infrastructure > Desktop Experience |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
286 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
287 2. **Start and set to Automatic WebClient Service**: Services > |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
288 WebClient > Properties > Set from Manual to Automatic then start it |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
289 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
290 `Link to the original post <https://groups.google.com/d/msgid/orthanc-users/3b3c3af1-0413-471e-8f31-0a358632fd6an%40googlegroups.com?utm_medium=email&utm_source=footer>`__ |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
291 |
63d59fab98e2
webdav on windows server 2012
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
529
diff
changeset
|
292 |
526 | 293 |
294 Debugging WebDAV | |
295 ---------------- | |
296 | |
297 As of release 1.8.0, the WebDAV server of Orthanc has been tested | |
298 against the following WebDAV clients: Nautilus, `davfs2 | |
299 <https://en.wikipedia.org/wiki/Davfs2>`__, Microsoft Windows XP, | |
300 Microsoft Windows 7, and Microsoft Windows 10. | |
301 | |
302 It is obviously impossible for us to test against all the possible | |
303 platforms. If you encounter an issue using your WebDAV client, you | |
304 should send us a trace generated by the `wsgidav reference server | |
305 <https://github.com/mar10/wsgidav/>`__ so that we can identify what is | |
306 the non-respect of Orthanc wrt. the WebDAV standard. | |
307 | |
308 .. highlight:: bash | |
309 | |
310 On Ubuntu, here are the commands to generate a useful log:: | |
311 | |
312 $ sudo pip install wsgidav cheroot | |
313 $ mkdir -p /tmp/webdav/hello | |
314 $ echo "foo" > /tmp/webdav/hello/world | |
315 $ wsgidav -v -v --auth anonymous --host=0.0.0.0 --port=8042 --root=/tmp/webdav/ | tee /tmp/wsgidav.log | |
316 | |
317 Connect your WebDAV client to ``http://localhost:8042/``, and do some | |
318 basic operations (access ``/hello/world``, create a file, create a | |
319 folder, and delete a file). Then, stop the ``wsgidav`` server and | |
320 publish the content of the ``/tmp/wsgidav.log`` logfile on the | |
321 `Orthanc Users discussion group | |
322 <https://groups.google.com/g/orthanc-users>`__. |