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