Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/troubleshooting.rst @ 681:9c23356b9464
typo: replaced "CheckRevision" by "CheckRevisions"
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Mon, 10 May 2021 12:30:57 +0200 |
| parents | a37ac06ec2fc |
| children | 1e6ead2a9901 |
| 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 | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
8 <https://www.orthanc-server.com/download.php>`__ of Orthanc. |
| 16 | 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 ------- | |
| 654 | 18 |
| 108 | 19 * If **Orthanc fails to start** with the error "**The TCP port of the DICOM |
| 20 server is privileged or already in use**", this means another software is | |
| 21 already using the port Orthanc is trying to use. Usually, this means | |
| 22 that an other instance of Orthanc is running. However, note that, by default, | |
| 23 Orthanc uses port 4242 which might also be used by other software like | |
| 24 a `Juniper VPN client <https://www.file.net/process/dsncservice.exe.html>`__. | |
| 25 To determine which other process is using the port: | |
| 26 | |
| 27 On Windows, you may use the `Resource Monitor <https://en.wikipedia.org/wiki/Resource_Monitor>`__. | |
| 28 In the `Network` tab, check the `Listening Ports`. | |
| 29 | |
| 30 On Linux, you may use this command line: ``sudo ss --tcp --listen --numeric --processes``. | |
| 31 | |
| 32 Starting with version 1.3.0, the check at Orthanc startup is more robust | |
| 33 (it also checks for UDP socket using the same port) and Orthanc 1.3.0 might | |
| 34 display error messages that where not displayed by previous versions. | |
| 16 | 35 |
| 654 | 36 |
| 37 Validating DICOM files | |
| 38 ---------------------- | |
| 39 | |
| 40 * Invalid DICOM files are often encountered in practice. Such files | |
| 41 can cause failures in Orthanc, or can prevent DICOM network | |
| 42 transfers. You can validate DICOM files by using the ``dciodvfy`` | |
| 43 command-line tool (cf. `its documentation | |
| 44 <http://dclunie.com/dicom3tools/dciodvfy.html>`__) from the | |
| 45 `dicom3tools <https://www.dclunie.com/dicom3tools.html>`__ project | |
| 46 by David Clunie. | |
| 47 | |
| 48 The core team of Orthanc will **only provide support for DICOM files | |
| 49 that are reported as valid** by ``dciodvfy``. | |
| 50 | |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
51 * Side-note: The default transfer syntax of DICOM is Little Endian |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
52 Implicit (``1.2.840.10008.1.2``). For DICOM files that include |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
53 private tags, **we recommend using Little Endian Explicit** |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
54 (``1.2.840.10008.1.2.1``) instead Little Endian Implicit whenever |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
55 possible. Instead, in Little Endian Explicit, each DICOM tag has an |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
56 explicit declaration of its value representation (type), which |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
57 contrasts with Little Endian Implicit that necessitates to configure |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
58 the dictionary of private tags to be properly handled in some |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
59 operations (cf. the ``Dictionary`` :ref:`configuration option |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
60 <configuration>`). |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
61 |
| 654 | 62 |
| 16 | 63 Orthanc Explorer |
| 64 ---------------- | |
| 65 | |
| 0 | 66 * **I cannot login to Orthanc Explorer**: For security reasons, access |
| 67 to Orthanc from remote hosts is disabled by default. Only the | |
| 68 localhost is allowed to access Orthanc. You have to set the | |
| 69 ``RemoteAccessAllowed`` option in the :ref:`configuration file | |
| 70 <configuration>` to ``true``. It is then strongly advised to set | |
| 71 ``AuthenticationEnabled`` to ``true`` and to add a user to the | |
| 72 ``RegisteredUsers`` option, also in the configuration file. | |
| 16 | 73 |
| 74 | |
| 75 Performance issues | |
| 76 ------------------ | |
| 77 | |
| 41 | 78 * **Run-time debug assertions**: If performance is important to you, |
| 79 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when | |
| 80 invoking ``cmake`` while :ref:`compiling Orthanc | |
| 81 <compiling>`. Indeed, by default, `run-time debug assertions | |
| 82 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_ | |
| 83 are enabled, which can seriously impact performance, especially if | |
| 84 your Orthanc server stores a lot of DICOM instances. | |
| 85 | |
| 86 Note that the `official Docker images | |
| 87 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0 | |
| 88 were not compiled in ``Release`` mode. As a consequence, to improve | |
| 89 performance, make sure to use either the mainline version of the | |
| 43 | 90 container (run ``docker pull jodogne/orthanc`` to ensure you use the |
| 91 most recent version of the mainline), or versions more recent than | |
| 122 | 92 ``jodogne/orthanc:1.1.0``. |
| 41 | 93 |
| 44 | 94 * **Orthanc slows down if storing many files**: The default database |
| 95 engine that is built in Orthanc is `SQLite | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
96 <https://www.sqlite.org/index.html>`__. As SQLite is above all a |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
97 lightweight database engine, it is not designed to `store very large |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
98 datasets <https://www.sqlite.org/whentouse.html>`__. If you are sure |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
99 that you have properly disabled run-time debug assertions |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
100 (cf. above), but still experience degradation in performance over |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
101 time, you should seriously consider switching to a more scalable |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
102 database engine. To this end, you can notably check out the |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
103 :ref:`official PostgreSQL plugin <postgresql>`. |
| 44 | 104 |
| 105 As a rule of thumb, the performance of the default SQLite engine | |
| 106 built in Orthanc should run fine up to about 50,000 DICOM instances. | |
| 188 | 107 However, we have seen Orthanc running fairly well with more than 2 |
| 108 millions of instances. This limit really depends upon your | |
| 109 application, and upon the patterns of access to the database. | |
| 110 | |
| 186 | 111 Also check out the section about the :ref:`scalability`. |
| 44 | 112 |
| 113 | |
| 18 | 114 * **Orthanc Explorer is slow under Windows on the localhost**: |
| 115 | |
| 116 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the | |
| 117 network address of a server. Users have reported that this minor | |
| 118 change `can massively improve performance | |
| 119 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__ | |
| 120 on Windows. Starting with Orthanc 1.0.1, the samples from the | |
| 121 source distribution have been adapted in this way. | |
| 122 | |
| 123 - As an alternative, you can disable IPv6 support. This is a | |
| 124 Windows-specific problem that is discussed `here | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
125 <https://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__ |
| 18 | 126 and `here |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
127 <https://stackoverflow.com/questions/1726585/firefox-and-chrome-slow-on-localhost-known-fix-doesnt-work-on-windows-7>`__. |
| 16 | 128 |
| 42 | 129 * If you experience **slow DICOM transfers under GNU/Linux**, please |
| 130 read the `following bug report | |
| 16 | 131 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785400>`__. This |
| 42 | 132 issue does *not* affect all the versions of GNU/Linux. A patch to |
| 133 this issue is shipped with the Orthanc source code. In order to take | |
| 134 advantage of this patch, you need to statically link Orthanc against | |
| 135 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking | |
| 136 CMake | |
| 360 | 137 <https://hg.orthanc-server.com/orthanc/file/default/LinuxCompilation.txt>`__. |
| 16 | 138 |
| 654 | 139 |
| 140 Checking integrity of the storage area | |
| 141 -------------------------------------- | |
| 142 | |
| 143 .. highlight:: bash | |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
144 |
| 654 | 145 Orthanc stores, in its database, an `MD5 hash |
| 146 <https://en.wikipedia.org/wiki/MD5>`_ of the files stored in its | |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
147 :ref:`storage area <orthanc-storage>` (which notably includes the |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
148 DICOM files), provided that the ``StoreMD5ForAttachments`` |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
149 configuration option is set to ``true``. |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
150 |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
151 This MD5 corresponds to the hash of the files in memory, before they |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
152 are written to the disk by Orthanc. This information is safely stored |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
153 inside the database for any incoming file attachment. |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
154 |
| 654 | 155 It is possible to ask Orthanc to check by itself whether some attachment |
| 156 file was corrupted (i.e. to check whether the MD5 hash stored in the | |
| 157 database corresponds to the hash of the file on the disk):: | |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
158 |
| 654 | 159 $ curl -X POST http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/verify-md5 -d '' |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
160 |
| 654 | 161 This MD5 may be different if errors occurred while the DICOM file was |
| 162 initially written to the storage, or if the file contents were | |
| 163 tampered with afterwards. | |
| 164 | |
| 165 You can retrieve the stored MD5 hash of a DICOM instance as follows:: | |
| 166 | |
| 167 $ curl http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/md5 | |
| 16 | 168 |
| 169 Windows-specific issues | |
| 170 ----------------------- | |
| 171 | |
| 0 | 172 * Under Windows, Orthanc creates the "OrthancStorage" folder, and |
| 173 crashes with the error "**SQLite: Unable to open the database**": | |
| 174 Your directory name is either too long, or it contains special | |
| 175 characters. Please try and run Orthanc in a folder with a simple | |
| 176 name such as ``C:\Orthanc``. | |
| 55 | 177 |
| 178 * If **Orthanc crashes when handling one large DICOM file**, this most | |
| 179 probably indicates a memory allocation error. Indeed, the `official | |
| 180 Windows binaries | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
181 <https://www.orthanc-server.com/download-windows.php>`__ are compiled |
| 55 | 182 using a 32bit compiler. As a consequence, Orthanc only has access to |
| 183 less than 4GB of RAM. If this is an important limitation for you, | |
| 184 precompiled command-line versions of Orthanc for Windows 64bit are | |
| 185 available courtesy of `Osimis | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
186 <https://www.osimis.io/en/download.html>`__. |
| 659 | 187 |
| 188 * Avoid installing Orthanc, its database or its storage area in | |
| 189 folders whose names contain **spaces or special characters**. |