Mercurial > hg > orthanc-book

comparison Sphinx/source/users/webdav.rst @ 526:e9d8c7e5afbd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>`__.