# HG changeset patch # User Sebastien Jodogne # Date 1602838436 -7200 # Node ID e9d8c7e5afbd47b93f32321866643222b9850506 # Parent f364b00bf02cfa46a8c8c00d24daf6128beb3a6f webdav diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/contributing.rst --- a/Sphinx/source/contributing.rst Thu Oct 15 16:13:56 2020 +0200 +++ b/Sphinx/source/contributing.rst Fri Oct 16 10:53:56 2020 +0200 @@ -107,13 +107,6 @@ + Have a look at the TODO file containing our `official roadmap `__. - - Develop a way to "mount" the content of one Orthanc server as a - network drive through the :ref:`REST API `, using either - `FTP `__, - `FUSE `__ - (through `Samba - `__ for Windows) - or `WebDAV `__. - Always remember that he **recommended way of contributing to the source code of Orthanc is by creating C/C++/Python plugins, or by creating external software that use the REST API**. If the current diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/faq/security.rst --- a/Sphinx/source/faq/security.rst Thu Oct 15 16:13:56 2020 +0200 +++ b/Sphinx/source/faq/security.rst Fri Oct 16 10:53:56 2020 +0200 @@ -45,7 +45,8 @@ * You might also be interested in checking the options related to :ref:`performance optimization `. - + +.. _security_http: Securing the HTTP server ------------------------ @@ -76,6 +77,9 @@ * Enable :ref:`Client certificate authentication ` between multiple Orthanc peers. +* Consider turning of the :ref:`embedded WebDAV server ` by + setting configuration option ``WebDavEnabled`` to ``false``. + * Setup rules that define, for each authorized user, which resources it can access, and through which HTTP method (GET, POST, DELETE and/or PUT). This can be done by defining a :ref:`filter written in diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-nautilus-1.png Binary file Sphinx/source/images/webdav-nautilus-1.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-nautilus-2.png Binary file Sphinx/source/images/webdav-nautilus-2.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config1.png Binary file Sphinx/source/images/webdav-win7-config1.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config2.png Binary file Sphinx/source/images/webdav-win7-config2.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config3.png Binary file Sphinx/source/images/webdav-win7-config3.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config4.png Binary file Sphinx/source/images/webdav-win7-config4.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config5.png Binary file Sphinx/source/images/webdav-win7-config5.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-config6.png Binary file Sphinx/source/images/webdav-win7-config6.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-sample.png Binary file Sphinx/source/images/webdav-win7-sample.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/images/webdav-win7-upload.png Binary file Sphinx/source/images/webdav-win7-upload.png has changed diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/users.rst --- a/Sphinx/source/users.rst Thu Oct 15 16:13:56 2020 +0200 +++ b/Sphinx/source/users.rst Fri Oct 16 10:53:56 2020 +0200 @@ -14,4 +14,5 @@ users/lua.rst users/advanced-rest.rst users/storage-commitment.rst + users/webdav.rst users/support.rst diff -r f364b00bf02c -r e9d8c7e5afbd Sphinx/source/users/webdav.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/webdav.rst Fri Oct 16 10:53:56 2020 +0200 @@ -0,0 +1,271 @@ +.. _webdav: + +Accessing Orthanc from the file explorer using WebDAV +===================================================== + +.. contents:: + +Since release 1.8.0, the content of an Orthanc server can be +**mapped/mounted as a network share** thanks to `WebDAV +`__. Thanks to this feature, you +can easily browse the DICOM instances that are stored by Orthanc using +the built-in file explorer of your operating system. It is possible to +download, upload or delete DICOM instances as well. + +Orthanc creates a so-called **virtual filesystem** that indexes the +same DICOM resources according to different views (data can be +accessed by patients, by studies, by date, or by DICOM UIDs). + + +.. _webdav_screenshots: + +Screenshots +----------- + +The screenshots below are generated using the `test virtual machines +`__ +that are provided by Microsoft. + +Here is the layout of the WebDAV server of Orthanc 1.8.0: + +.. image:: ../images/webdav-win7-sample.png + :align: center + :width: 512 + +As can be noticed, Orthanc exposes a full hierarchy of DICOM +resources. These resources are transparently mapped to the database of +Orthanc. The same resource will appear at multiple locations of this +virtual filesystem, but in practice, it is stored only once. One can +choose the best way to access the information depending on the use +case. + +Uploading a full folder containing a DICOM study (such as a CD or a +DVD containing a DICOMDIR) is as simple as a drag-and-drop onto the +``/uploads/`` folder: + +.. image:: ../images/webdav-win7-upload.png + :align: center + :width: 512 + + +Server configuration +-------------------- + +Options +^^^^^^^ + +Three configuration options can be used to configure the WebDAV +server: + +* ``WebDavEnabled`` to enable/disable WebDAV. + +* ``WebDavDeleteAllowed`` to turn on/off the possibility of deleting + DICOM resources using WebDAV. This can be disabled for security + reasons. + +* ``WebDavUploadAllowed`` to turn on/off the possibility of uploading + DICOM resources using WebDAV. + + +Security +^^^^^^^^ + +As WebDAV is an application layer above HTTP, you should pay attention +to :ref:`protect your HTTP server `. At the minimum, +you should enable HTTP Basic Authentication (check out configuration +option ``RegisteredUsers``). The client will have to provide her +credentials when mapping the WebDAV share. + +If you want to control which user can see which resource, you should +protect your network share by creating **access control lists** +through a :ref:`Lua script `, through the +:ref:`advanced authorization plugin `, or through +:ref:`your own plugin ` +(cf. ``OrthancPluginRegisterIncomingHttpRequestFilter2()``). + +The HTTP methods that are used by WebDAV are ``GET`` (for read-only +accesses), ``PUT`` (for uploads), and ``DELETE`` (for deletions). The +access control lists can be focused on these methods. + +Finally, it is highly recommended to enable :ref:`HTTPS encryption +`, which might need additional configuration on some operating +systems (see below for Microsoft Windows 10). + + +Client configuration +-------------------- + +Nautilus on Ubuntu 18.04 +^^^^^^^^^^^^^^^^^^^^^^^^ + +It is quite straightforward to use the WebDAV server using Nautilus on +Ubuntu: + +.. image:: ../images/webdav-nautilus-1.png + :align: center + :width: 512 + +Obviously, adapt the IP address and HTTP port number to your setup. +Once the share is connected, it is readily accessible: + +.. image:: ../images/webdav-nautilus-2.png + :align: center + :width: 512 + +**Important:** If you use :ref:`HTTPS encryption `, which is +recommended for security reasons, replace the prefix ``dav://`` by +``davs://``. + + +Microsoft Windows 7 +^^^^^^^^^^^^^^^^^^^ + +This section illustrates how to use WebDAV on a Microsoft Windows 7 +operating system. Obviously, the procedure is very similar for more +recent versions of Microsoft Windows, and many tutorials are available +on Internet. + +WebDAV has a `known performance issue +`__ +on barebone Microsoft Windows 7. To fix this issue, first open the +"Internet Properties" configuration panel: + +.. image:: ../images/webdav-win7-config5.png + :align: center + :width: 512 + +Then simply uncheck the "Automatically detect settings" checkbox in +the "LAN settings" panel: + +.. image:: ../images/webdav-win7-config6.png + :align: center + :width: 384 + +Once this is done, in order to map Orthanc as a network share on +Microsoft Windows 7, first open the File Explorer, and right-click on +"Computer": + +.. image:: ../images/webdav-win7-config1.png + :align: center + :width: 512 + +This will open the "Add Network Location Wizard". Click on "Next" to +choose the (only) available option: + +.. image:: ../images/webdav-win7-config2.png + :align: center + :width: 384 + +Now enter the IP address and the HTTP port of your Orthanc server, and +don't forget to add the ``/webdav/`` suffix: + +.. image:: ../images/webdav-win7-config3.png + :align: center + :width: 384 + +Give a name to your network share: + +.. image:: ../images/webdav-win7-config4.png + :align: center + :width: 384 + +At the "Completing the Add Network Location Wizard", click on +"Finish". You'll then be able to use the network share as depicted in +the :ref:`screenshots above `. + +**Important:** For some reason, Microsoft Windows 7 sometimes "`gets +lost +`__" +after an upload and cannot access Orthanc anymore. In such situations, +you'll have to delete the network share and repeat the steps above +again. + + +Remote access using Microsoft Windows 10 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on your security settings, `Microsoft Windows 10 might impose +the use of HTTPS <>`__ in the Orthanc server. First, you must obviously +configure :ref:`HTTPS security in Orthanc `. + +In order to connect successfully to Orthanc WebDAV server using basic +authentication and SSL with self-signed certificate. + +1) download the ``.pem`` certificate + +2) Open "Control Panel" → "Manage Computer Certificates" + +3) Right click on "Certificates - Local Computer → Trusted Root + Certification Authorities → Certificates" and choose "All Tasks → + Import..." + +4) Select the ``.pem`` certificate (you might need to enforce + displaying ``*.*`` files in the dialog box, for the ``.pem`` + extension is not part of the standard certificate extensions) + +5) Choose "Place all certifications in the following store: Trusted + Root Certification Authorities" + +6) A dialog box should pop up with "The import was successful" + +When done, you can test the WebDAV connection : + +1) Right click on the Explorer namespace root ("This PC", in Windows 10) + +2) Choose "Map Network Drive" + +3) Click the link named "Connect to a Web site that you can use..." + +4) Choose custom network location + +5) Type the WebDAV address like: ``http://10.10.10.107:8042/webdav/`` + +6) If all goes well, you should be prompted for the basic auth credentials. + +When this is done, the WebDAV location should be mounted at the top of +the Explorer namespace (next to the C: drive, etc...). Something to +try if the mount fails: + +- open ``regedit.exe`` + +- open the ``HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters key`` + +- create the ``BasicAuthLevel`` DWORD value if needed + +- set the ``BasicAuthLevel`` DWORD value to ``2`` + +This should *not* be required, but was enabled on the PC that was used +to test the mounting procedure. `Details here +`__ + + + +Debugging WebDAV +---------------- + +As of release 1.8.0, the WebDAV server of Orthanc has been tested +against the following WebDAV clients: Nautilus, `davfs2 +`__, Microsoft Windows XP, +Microsoft Windows 7, and Microsoft Windows 10. + +It is obviously impossible for us to test against all the possible +platforms. If you encounter an issue using your WebDAV client, you +should send us a trace generated by the `wsgidav reference server +`__ so that we can identify what is +the non-respect of Orthanc wrt. the WebDAV standard. + +.. highlight:: bash + +On Ubuntu, here are the commands to generate a useful log:: + + $ sudo pip install wsgidav cheroot + $ mkdir -p /tmp/webdav/hello + $ echo "foo" > /tmp/webdav/hello/world + $ wsgidav -v -v --auth anonymous --host=0.0.0.0 --port=8042 --root=/tmp/webdav/ | tee /tmp/wsgidav.log + +Connect your WebDAV client to ``http://localhost:8042/``, and do some +basic operations (access ``/hello/world``, create a file, create a +folder, and delete a file). Then, stop the ``wsgidav`` server and +publish the content of the ``/tmp/wsgidav.log`` logfile on the +`Orthanc Users discussion group +`__.