|
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
|
|
|
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>`__.
|
