Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/troubleshooting.rst @ 902:7f30e05a3319
note about Windows service
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Tue, 20 Dec 2022 08:12:17 +0100 |
parents | 628035820f1c |
children | 25bbeb754420 |
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 |
754
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
36 * If Orthanc **does not start anymore after a hard shutdown** and if |
755 | 37 you use the :ref:`Orthanc Web viewer plugin <webviewer>`, this might |
754
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
38 reflect a corruption in the cache of the Web viewer. In such a case, |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
39 it is safe to remove the folder that contains the cache. By default, |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
40 this folder is called ``OrthancStorage/WebViewerCache/`` |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
41 (cf. :ref:`configuration option <configuration>` ``CachePath`` in |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
42 the ``WebViewer`` section). Of course, don't remove the folder |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
43 ``OrthancStorage/``, as it contains the DICOM files. |
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
44 |
654 | 45 |
46 Validating DICOM files | |
47 ---------------------- | |
48 | |
49 * Invalid DICOM files are often encountered in practice. Such files | |
50 can cause failures in Orthanc, or can prevent DICOM network | |
51 transfers. You can validate DICOM files by using the ``dciodvfy`` | |
52 command-line tool (cf. `its documentation | |
53 <http://dclunie.com/dicom3tools/dciodvfy.html>`__) from the | |
54 `dicom3tools <https://www.dclunie.com/dicom3tools.html>`__ project | |
55 by David Clunie. | |
56 | |
57 The core team of Orthanc will **only provide support for DICOM files | |
58 that are reported as valid** by ``dciodvfy``. | |
59 | |
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
60 * 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
|
61 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
|
62 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
|
63 (``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
|
64 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
|
65 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
|
66 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
|
67 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
|
68 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
|
69 <configuration>`). |
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
70 |
654 | 71 |
16 | 72 Orthanc Explorer |
73 ---------------- | |
74 | |
0 | 75 * **I cannot login to Orthanc Explorer**: For security reasons, access |
76 to Orthanc from remote hosts is disabled by default. Only the | |
77 localhost is allowed to access Orthanc. You have to set the | |
78 ``RemoteAccessAllowed`` option in the :ref:`configuration file | |
79 <configuration>` to ``true``. It is then strongly advised to set | |
80 ``AuthenticationEnabled`` to ``true`` and to add a user to the | |
81 ``RegisteredUsers`` option, also in the configuration file. | |
16 | 82 |
83 | |
84 Performance issues | |
85 ------------------ | |
86 | |
41 | 87 * **Run-time debug assertions**: If performance is important to you, |
88 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when | |
89 invoking ``cmake`` while :ref:`compiling Orthanc | |
90 <compiling>`. Indeed, by default, `run-time debug assertions | |
91 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_ | |
92 are enabled, which can seriously impact performance, especially if | |
93 your Orthanc server stores a lot of DICOM instances. | |
94 | |
95 Note that the `official Docker images | |
96 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0 | |
97 were not compiled in ``Release`` mode. As a consequence, to improve | |
98 performance, make sure to use either the mainline version of the | |
43 | 99 container (run ``docker pull jodogne/orthanc`` to ensure you use the |
100 most recent version of the mainline), or versions more recent than | |
122 | 101 ``jodogne/orthanc:1.1.0``. |
41 | 102 |
44 | 103 * **Orthanc slows down if storing many files**: The default database |
104 engine that is built in Orthanc is `SQLite | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
105 <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
|
106 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
|
107 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
|
108 that you have properly disabled run-time debug assertions |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
109 (cf. above), but still experience degradation in performance over |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
110 time, you should seriously consider switching to a more scalable |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
111 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
|
112 :ref:`official PostgreSQL plugin <postgresql>`. |
44 | 113 |
114 As a rule of thumb, the performance of the default SQLite engine | |
115 built in Orthanc should run fine up to about 50,000 DICOM instances. | |
188 | 116 However, we have seen Orthanc running fairly well with more than 2 |
117 millions of instances. This limit really depends upon your | |
118 application, and upon the patterns of access to the database. | |
119 | |
186 | 120 Also check out the section about the :ref:`scalability`. |
44 | 121 |
122 | |
18 | 123 * **Orthanc Explorer is slow under Windows on the localhost**: |
124 | |
125 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the | |
126 network address of a server. Users have reported that this minor | |
127 change `can massively improve performance | |
128 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__ | |
129 on Windows. Starting with Orthanc 1.0.1, the samples from the | |
130 source distribution have been adapted in this way. | |
131 | |
132 - As an alternative, you can disable IPv6 support. This is a | |
133 Windows-specific problem that is discussed `here | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
134 <https://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__ |
18 | 135 and `here |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
136 <https://stackoverflow.com/questions/1726585/firefox-and-chrome-slow-on-localhost-known-fix-doesnt-work-on-windows-7>`__. |
16 | 137 |
42 | 138 * If you experience **slow DICOM transfers under GNU/Linux**, please |
139 read the `following bug report | |
16 | 140 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785400>`__. This |
42 | 141 issue does *not* affect all the versions of GNU/Linux. A patch to |
142 this issue is shipped with the Orthanc source code. In order to take | |
143 advantage of this patch, you need to statically link Orthanc against | |
144 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking | |
145 CMake | |
360 | 146 <https://hg.orthanc-server.com/orthanc/file/default/LinuxCompilation.txt>`__. |
16 | 147 |
654 | 148 |
149 Checking integrity of the storage area | |
150 -------------------------------------- | |
151 | |
152 .. highlight:: bash | |
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
153 |
654 | 154 Orthanc stores, in its database, an `MD5 hash |
155 <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
|
156 :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
|
157 DICOM files), provided that the ``StoreMD5ForAttachments`` |
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
158 configuration option is set to ``true``. |
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
159 |
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
160 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
|
161 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
|
162 inside the database for any incoming file attachment. |
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
163 |
654 | 164 It is possible to ask Orthanc to check by itself whether some attachment |
165 file was corrupted (i.e. to check whether the MD5 hash stored in the | |
166 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
|
167 |
654 | 168 $ 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
|
169 |
654 | 170 This MD5 may be different if errors occurred while the DICOM file was |
171 initially written to the storage, or if the file contents were | |
172 tampered with afterwards. | |
173 | |
174 You can retrieve the stored MD5 hash of a DICOM instance as follows:: | |
175 | |
176 $ curl http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/md5 | |
16 | 177 |
178 Windows-specific issues | |
179 ----------------------- | |
180 | |
0 | 181 * Under Windows, Orthanc creates the "OrthancStorage" folder, and |
182 crashes with the error "**SQLite: Unable to open the database**": | |
183 Your directory name is either too long, or it contains special | |
184 characters. Please try and run Orthanc in a folder with a simple | |
185 name such as ``C:\Orthanc``. | |
55 | 186 |
187 * If **Orthanc crashes when handling one large DICOM file**, this most | |
188 probably indicates a memory allocation error. Indeed, the `official | |
189 Windows binaries | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
190 <https://www.orthanc-server.com/download-windows.php>`__ are compiled |
55 | 191 using a 32bit compiler. As a consequence, Orthanc only has access to |
192 less than 4GB of RAM. If this is an important limitation for you, | |
193 precompiled command-line versions of Orthanc for Windows 64bit are | |
194 available courtesy of `Osimis | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
195 <https://www.osimis.io/en/download.html>`__. |
659 | 196 |
197 * Avoid installing Orthanc, its database or its storage area in | |
198 folders whose names contain **spaces or special characters**. | |
902
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
199 |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
200 * If you run Orthanc as a Windows service, with the Python plugin |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
201 enabled, you might have to change your ``PATH`` environment variable |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
202 for Orthanc to find the Python DLL. The easiest approach to this end |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
203 consists in configuring the Windows service to **run as user** |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
204 (instead of the default ``SYSTEM`` account), `as explained in this |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
205 thread |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
206 <https://groups.google.com/g/orthanc-users/c/axrJfgA-Enk/m/Zeg3iUPOAwAJ>`__ |
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
207 on the Orthanc Users forum. |