annotate Sphinx/source/faq/troubleshooting.rst @ 544:d7ec7ea133b8

note about nginx to emulate dicom tls
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 12 Nov 2020 09:26:24 +0100
parents d217af5e6cb3
children e66534972166
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _troubleshooting:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Troubleshooting
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 ===============
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
6 As a general rule, when you encounter an issue, always make sure that
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
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
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
9
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
10 Also make a search on the `Orthanc Users discussion group
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
11 <https://groups.google.com/forum/#!forum/orthanc-users>`__, and make a
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
12 search in the present Orthanc Book (there is a search field at the top
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
13 of this page). Your issue might indeed have already been discussed in
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
14 the past or in the FAQ.
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
15
108
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
16 Startup
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
17 -------
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
18 * If **Orthanc fails to start** with the error "**The TCP port of the DICOM
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
19 server is privileged or already in use**", this means another software is
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
20 already using the port Orthanc is trying to use. Usually, this means
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
21 that an other instance of Orthanc is running. However, note that, by default,
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
22 Orthanc uses port 4242 which might also be used by other software like
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
23 a `Juniper VPN client <https://www.file.net/process/dsncservice.exe.html>`__.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
24 To determine which other process is using the port:
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
25
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
26 On Windows, you may use the `Resource Monitor <https://en.wikipedia.org/wiki/Resource_Monitor>`__.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
27 In the `Network` tab, check the `Listening Ports`.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
28
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
29 On Linux, you may use this command line: ``sudo ss --tcp --listen --numeric --processes``.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
30
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
31 Starting with version 1.3.0, the check at Orthanc startup is more robust
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
32 (it also checks for UDP socket using the same port) and Orthanc 1.3.0 might
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
33 display error messages that where not displayed by previous versions.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
34
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
35 Orthanc Explorer
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
36 ----------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
37
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 * **I cannot login to Orthanc Explorer**: For security reasons, access
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 to Orthanc from remote hosts is disabled by default. Only the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 localhost is allowed to access Orthanc. You have to set the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 ``RemoteAccessAllowed`` option in the :ref:`configuration file
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 <configuration>` to ``true``. It is then strongly advised to set
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 ``AuthenticationEnabled`` to ``true`` and to add a user to the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44 ``RegisteredUsers`` option, also in the configuration file.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
45
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
46
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
47 Performance issues
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
48 ------------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
49
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
50 * **Run-time debug assertions**: If performance is important to you,
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
51 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
52 invoking ``cmake`` while :ref:`compiling Orthanc
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
53 <compiling>`. Indeed, by default, `run-time debug assertions
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
54 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
55 are enabled, which can seriously impact performance, especially if
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
56 your Orthanc server stores a lot of DICOM instances.
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
57
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
58 Note that the `official Docker images
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
59 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
60 were not compiled in ``Release`` mode. As a consequence, to improve
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
61 performance, make sure to use either the mainline version of the
43
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
62 container (run ``docker pull jodogne/orthanc`` to ensure you use the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
63 most recent version of the mainline), or versions more recent than
122
9badd112e8ad Orthanc 1.3.1
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 109
diff changeset
64 ``jodogne/orthanc:1.1.0``.
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
65
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
66 * **Orthanc slows down if storing many files**: The default database
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
67 engine that is built in Orthanc is `SQLite
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
68 <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
69 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
70 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
71 that you have properly disabled run-time debug assertions
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
72 (cf. above), but still experience degradation in performance over
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
73 time, you should seriously consider switching to a more scalable
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
74 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
75 :ref:`official PostgreSQL plugin <postgresql>`.
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
76
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
77 As a rule of thumb, the performance of the default SQLite engine
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
78 built in Orthanc should run fine up to about 50,000 DICOM instances.
188
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
79 However, we have seen Orthanc running fairly well with more than 2
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
80 millions of instances. This limit really depends upon your
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
81 application, and upon the patterns of access to the database.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
82
186
a846a8f6d9a6 scalability
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 122
diff changeset
83 Also check out the section about the :ref:`scalability`.
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
84
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
85
18
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
86 * **Orthanc Explorer is slow under Windows on the localhost**:
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
87
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
88 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
89 network address of a server. Users have reported that this minor
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
90 change `can massively improve performance
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
91 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
92 on Windows. Starting with Orthanc 1.0.1, the samples from the
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
93 source distribution have been adapted in this way.
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
94
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
95 - As an alternative, you can disable IPv6 support. This is a
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
96 Windows-specific problem that is discussed `here
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
97 <https://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__
18
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
98 and `here
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
99 <https://stackoverflow.com/questions/1726585/firefox-and-chrome-slow-on-localhost-known-fix-doesnt-work-on-windows-7>`__.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
100
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
101 * If you experience **slow DICOM transfers under GNU/Linux**, please
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
102 read the `following bug report
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
103 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785400>`__. This
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
104 issue does *not* affect all the versions of GNU/Linux. A patch to
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
105 this issue is shipped with the Orthanc source code. In order to take
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
106 advantage of this patch, you need to statically link Orthanc against
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
107 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
108 CMake
360
d217af5e6cb3 links to hg
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
109 <https://hg.orthanc-server.com/orthanc/file/default/LinuxCompilation.txt>`__.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
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
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
126
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
127 Windows-specific issues
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
128 -----------------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
129
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
130 * Under Windows, Orthanc creates the "OrthancStorage" folder, and
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
131 crashes with the error "**SQLite: Unable to open the database**":
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
132 Your directory name is either too long, or it contains special
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
133 characters. Please try and run Orthanc in a folder with a simple
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
134 name such as ``C:\Orthanc``.
55
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
135
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
136 * If **Orthanc crashes when handling one large DICOM file**, this most
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
137 probably indicates a memory allocation error. Indeed, the `official
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
138 Windows binaries
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
139 <https://www.orthanc-server.com/download-windows.php>`__ are compiled
55
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
140 using a 32bit compiler. As a consequence, Orthanc only has access to
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
141 less than 4GB of RAM. If this is an important limitation for you,
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
142 precompiled command-line versions of Orthanc for Windows 64bit are
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
143 available courtesy of `Osimis
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
144 <https://www.osimis.io/en/download.html>`__.