Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/troubleshooting.rst @ 195:d36b87537641
Added more LF to ease reading
| author | bgo-osimis |
|---|---|
| date | Mon, 04 Feb 2019 09:54:28 +0100 |
| parents | 99ba212989cc |
| children | 011b01ccf52d |
| rev | line source |
|---|---|
| 0 | 1 .. _troubleshooting: |
| 2 | |
| 3 Troubleshooting | |
| 4 =============== | |
| 5 | |
| 16 | 6 As a general rule, when you encounter an issue, always make sure that |
| 7 you use the `most recent version | |
| 8 <http://www.orthanc-server.com/download.php>`__ of Orthanc. | |
| 9 | |
| 10 Also make a search on the `Orthanc Users discussion group | |
| 11 <https://groups.google.com/forum/#!forum/orthanc-users>`__, and make a | |
| 12 search in the present Orthanc Book (there is a search field at the top | |
| 13 of this page). Your issue might indeed have already been discussed in | |
| 14 the past or in the FAQ. | |
| 15 | |
| 108 | 16 Startup |
| 17 ------- | |
| 18 * If **Orthanc fails to start** with the error "**The TCP port of the DICOM | |
| 19 server is privileged or already in use**", this means another software is | |
| 20 already using the port Orthanc is trying to use. Usually, this means | |
| 21 that an other instance of Orthanc is running. However, note that, by default, | |
| 22 Orthanc uses port 4242 which might also be used by other software like | |
| 23 a `Juniper VPN client <https://www.file.net/process/dsncservice.exe.html>`__. | |
| 24 To determine which other process is using the port: | |
| 25 | |
| 26 On Windows, you may use the `Resource Monitor <https://en.wikipedia.org/wiki/Resource_Monitor>`__. | |
| 27 In the `Network` tab, check the `Listening Ports`. | |
| 28 | |
| 29 On Linux, you may use this command line: ``sudo ss --tcp --listen --numeric --processes``. | |
| 30 | |
| 31 Starting with version 1.3.0, the check at Orthanc startup is more robust | |
| 32 (it also checks for UDP socket using the same port) and Orthanc 1.3.0 might | |
| 33 display error messages that where not displayed by previous versions. | |
| 16 | 34 |
| 35 Orthanc Explorer | |
| 36 ---------------- | |
| 37 | |
| 0 | 38 * **I cannot login to Orthanc Explorer**: For security reasons, access |
| 39 to Orthanc from remote hosts is disabled by default. Only the | |
| 40 localhost is allowed to access Orthanc. You have to set the | |
| 41 ``RemoteAccessAllowed`` option in the :ref:`configuration file | |
| 42 <configuration>` to ``true``. It is then strongly advised to set | |
| 43 ``AuthenticationEnabled`` to ``true`` and to add a user to the | |
| 44 ``RegisteredUsers`` option, also in the configuration file. | |
| 16 | 45 |
| 46 | |
| 47 Performance issues | |
| 48 ------------------ | |
| 49 | |
| 41 | 50 * **Run-time debug assertions**: If performance is important to you, |
| 51 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when | |
| 52 invoking ``cmake`` while :ref:`compiling Orthanc | |
| 53 <compiling>`. Indeed, by default, `run-time debug assertions | |
| 54 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_ | |
| 55 are enabled, which can seriously impact performance, especially if | |
| 56 your Orthanc server stores a lot of DICOM instances. | |
| 57 | |
| 58 Note that the `official Docker images | |
| 59 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0 | |
| 60 were not compiled in ``Release`` mode. As a consequence, to improve | |
| 61 performance, make sure to use either the mainline version of the | |
| 43 | 62 container (run ``docker pull jodogne/orthanc`` to ensure you use the |
| 63 most recent version of the mainline), or versions more recent than | |
| 122 | 64 ``jodogne/orthanc:1.1.0``. |
| 41 | 65 |
| 44 | 66 * **Orthanc slows down if storing many files**: The default database |
| 67 engine that is built in Orthanc is `SQLite | |
| 68 <https://www.sqlite.org/>`__. As SQLite is above all a lightweight | |
| 69 database engine, it is not designed to `store very large datasets | |
| 70 <https://www.sqlite.org/whentouse.html>`__. If you are sure that you | |
| 71 have properly disabled run-time debug assertions (cf. above), but | |
| 72 still experience degradation in performance over time, you should | |
| 73 seriously consider switching to a more scalable database engine. To | |
| 74 this end, you can notably check out the :ref:`official PostgreSQL | |
| 75 plugin <postgresql>`. | |
| 76 | |
| 77 As a rule of thumb, the performance of the default SQLite engine | |
| 78 built in Orthanc should run fine up to about 50,000 DICOM instances. | |
| 188 | 79 However, we have seen Orthanc running fairly well with more than 2 |
| 80 millions of instances. This limit really depends upon your | |
| 81 application, and upon the patterns of access to the database. | |
| 82 | |
| 186 | 83 Also check out the section about the :ref:`scalability`. |
| 44 | 84 |
| 85 | |
| 18 | 86 * **Orthanc Explorer is slow under Windows on the localhost**: |
| 87 | |
| 88 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the | |
| 89 network address of a server. Users have reported that this minor | |
| 90 change `can massively improve performance | |
| 91 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__ | |
| 92 on Windows. Starting with Orthanc 1.0.1, the samples from the | |
| 93 source distribution have been adapted in this way. | |
| 94 | |
| 95 - As an alternative, you can disable IPv6 support. This is a | |
| 96 Windows-specific problem that is discussed `here | |
| 97 <http://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__ | |
| 98 and `here | |
| 99 <http://stackoverflow.com/questions/1726585/firefox-and-chrome-slow-on-localhost-known-fix-doesnt-work-on-windows-7>`__. | |
| 16 | 100 |
| 42 | 101 * If you experience **slow DICOM transfers under GNU/Linux**, please |
| 102 read the `following bug report | |
| 16 | 103 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785400>`__. This |
| 42 | 104 issue does *not* affect all the versions of GNU/Linux. A patch to |
| 105 this issue is shipped with the Orthanc source code. In order to take | |
| 106 advantage of this patch, you need to statically link Orthanc against | |
| 107 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking | |
| 108 CMake | |
| 16 | 109 <https://bitbucket.org/sjodogne/orthanc/src/default/LinuxCompilation.txt>`__. |
| 110 | |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
111 Checking DICOM file integrity |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
112 ----------------------------- |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
113 Orthanc stores, in its database, an `MD5 hash <https://en.wikipedia.org/wiki/MD5>`_ of the DICOM file contents. |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
114 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
115 This MD5 corresponds to the hash of the DICOM file in memory, before it is written to the disk by Orthanc. This information is safely stored inside the database for any incoming DICOM file (provided that the ``StoreMD5ForAttachments`` configuration option is set to ``true``). |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
116 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
117 It ispossible to ask Orthanc to check by itself whether the DICOM file was corrupted (i.e. to check whether the MD5 hash stored in the database corresponds to the hash of the file on the disk): |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
118 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
119 ``curl -X POST http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/verify-md5 -d ''`` |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
120 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
121 This MD5 may be different if errors occurred while the DICOM file was initially written to the storage, or if the file contents were tampered with afterwards. |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
122 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
123 You can retrieve the stored MD5 hash of a DICOM instance as follows: |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
124 |
|
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
125 ``curl http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/md5`` |
| 16 | 126 |
| 127 Windows-specific issues | |
| 128 ----------------------- | |
| 129 | |
| 0 | 130 * Under Windows, Orthanc creates the "OrthancStorage" folder, and |
| 131 crashes with the error "**SQLite: Unable to open the database**": | |
| 132 Your directory name is either too long, or it contains special | |
| 133 characters. Please try and run Orthanc in a folder with a simple | |
| 134 name such as ``C:\Orthanc``. | |
| 55 | 135 |
| 136 * If **Orthanc crashes when handling one large DICOM file**, this most | |
| 137 probably indicates a memory allocation error. Indeed, the `official | |
| 138 Windows binaries | |
| 139 <http://www.orthanc-server.com/download-windows.php>`__ are compiled | |
| 140 using a 32bit compiler. As a consequence, Orthanc only has access to | |
| 141 less than 4GB of RAM. If this is an important limitation for you, | |
| 142 precompiled command-line versions of Orthanc for Windows 64bit are | |
| 143 available courtesy of `Osimis | |
| 122 | 144 <http://www.osimis.io/en/download.html>`__. |