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