annotate Sphinx/source/faq/troubleshooting.rst @ 1075:d2be251975d1 Orthanc-1.12.4

Orthanc 1.12.4
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 05 Jun 2024 20:18:43 +0200
parents 2cc02026ecbf
children
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
984
46e2941b57dd replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents: 903
diff changeset
10 Also make a search on the `Orthanc Users discussion forum
46e2941b57dd replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents: 903
diff changeset
11 <https://discourse.orthanc-server.org>`__, and make a
16
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 -------
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
18
108
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
19 * If **Orthanc fails to start** with the error "**The TCP port of the DICOM
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
20 server is privileged or already in use**", this means another software is
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
21 already using the port Orthanc is trying to use. Usually, this means
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
22 that an other instance of Orthanc is running. However, note that, by default,
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
23 Orthanc uses port 4242 which might also be used by other software like
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
24 a `Juniper VPN client <https://www.file.net/process/dsncservice.exe.html>`__.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
25 To determine which other process is using the port:
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
26
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
27 On Windows, you may use the `Resource Monitor <https://en.wikipedia.org/wiki/Resource_Monitor>`__.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
28 In the `Network` tab, check the `Listening Ports`.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
29
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
30 On Linux, you may use this command line: ``sudo ss --tcp --listen --numeric --processes``.
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
31
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
32 Starting with version 1.3.0, the check at Orthanc startup is more robust
e3be44c1d041 added startup troubleshooting
amazy
parents: 72
diff changeset
33 (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
34 display error messages that where not displayed by previous versions.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
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
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 754
diff changeset
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
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
45
1050
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
46 DICOM networking
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
47 ----------------
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
48
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
49 * The troubleshooting of DICOM network protocol is covered in a
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
50 :ref:`separate FAQ entry <dicom>`.
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
51
2cc02026ecbf link to troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 1004
diff changeset
52
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
53 Validating DICOM files
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
54 ----------------------
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
55
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
56 * Invalid DICOM files are often encountered in practice. Such files
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
57 can cause failures in Orthanc, or can prevent DICOM network
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
58 transfers. You can validate DICOM files by using the ``dciodvfy``
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
59 command-line tool (cf. `its documentation
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
60 <http://dclunie.com/dicom3tools/dciodvfy.html>`__) from the
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
61 `dicom3tools <https://www.dclunie.com/dicom3tools.html>`__ project
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
62 by David Clunie.
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
63
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
64 The core team of Orthanc will **only provide support for DICOM files
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
65 that are reported as valid** by ``dciodvfy``.
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
66
656
55a93745e874 use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 654
diff changeset
67 * 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
68 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
69 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
70 (``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
71 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
72 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
73 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
74 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
75 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
76 <configuration>`).
55a93745e874 use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 654
diff changeset
77
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
78
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
79 Orthanc Explorer
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
80 ----------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
81
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 * **I cannot login to Orthanc Explorer**: For security reasons, access
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 to Orthanc from remote hosts is disabled by default. Only the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84 localhost is allowed to access Orthanc. You have to set the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 ``RemoteAccessAllowed`` option in the :ref:`configuration file
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 <configuration>` to ``true``. It is then strongly advised to set
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 ``AuthenticationEnabled`` to ``true`` and to add a user to the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88 ``RegisteredUsers`` option, also in the configuration file.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
89
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
90
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
91 Performance issues
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
92 ------------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
93
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
94 * **Run-time debug assertions**: If performance is important to you,
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
95 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
96 invoking ``cmake`` while :ref:`compiling Orthanc
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
97 <compiling>`. Indeed, by default, `run-time debug assertions
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
98 <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
99 are enabled, which can seriously impact performance, especially if
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
100 your Orthanc server stores a lot of DICOM instances.
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
101
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
102 Note that the `official Docker images
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
103 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
104 were not compiled in ``Release`` mode. As a consequence, to improve
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
105 performance, make sure to use either the mainline version of the
43
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
106 container (run ``docker pull jodogne/orthanc`` to ensure you use the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
107 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
108 ``jodogne/orthanc:1.1.0``.
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 18
diff changeset
109
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
110 * **Orthanc slows down if storing many files**: The default database
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
111 engine that is built in Orthanc is `SQLite
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
112 <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
113 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
114 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
115 that you have properly disabled run-time debug assertions
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
116 (cf. above), but still experience degradation in performance over
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
117 time, you should seriously consider switching to a more scalable
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
118 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
119 :ref:`official PostgreSQL plugin <postgresql>`.
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
120
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
121 As a rule of thumb, the performance of the default SQLite engine
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
122 built in Orthanc should run fine up to about 50,000 DICOM instances.
188
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
123 However, we have seen Orthanc running fairly well with more than 2
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
124 millions of instances. This limit really depends upon your
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
125 application, and upon the patterns of access to the database.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 186
diff changeset
126
186
a846a8f6d9a6 scalability
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 122
diff changeset
127 Also check out the section about the :ref:`scalability`.
44
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
128
23d5a5a84287 performance
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 43
diff changeset
129
18
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
130 * **Orthanc Explorer is slow under Windows on the localhost**:
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
131
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
132 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
133 network address of a server. Users have reported that this minor
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
134 change `can massively improve performance
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
135 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
136 on Windows. Starting with Orthanc 1.0.1, the samples from the
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
137 source distribution have been adapted in this way.
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
138
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
139 - As an alternative, you can disable IPv6 support. This is a
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
140 Windows-specific problem that is discussed `here
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
141 <https://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__
18
dabe6df0267f localhost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 16
diff changeset
142 and `here
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 193
diff changeset
143 <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
144
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
145 * If you experience **slow DICOM transfers under GNU/Linux**, please
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
146 read the `following bug report
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
147 <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
148 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
149 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
150 advantage of this patch, you need to statically link Orthanc against
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
151 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
152 CMake
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 984
diff changeset
153 <https://orthanc.uclouvain.be/hg/orthanc/file/default/LinuxCompilation.txt>`__.
16
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
154
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
155
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
156 Checking integrity of the storage area
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
157 --------------------------------------
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
158
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
159 .. highlight:: bash
193
99ba212989cc Added entry related to MD5 integrity file checking
bgo-osimis
parents: 188
diff changeset
160
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
161 Orthanc stores, in its database, an `MD5 hash
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
162 <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
163 :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
164 DICOM files), provided that the ``StoreMD5ForAttachments``
55a93745e874 use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 654
diff changeset
165 configuration option is set to ``true``.
193
99ba212989cc Added entry related to MD5 integrity file checking
bgo-osimis
parents: 188
diff changeset
166
656
55a93745e874 use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 654
diff changeset
167 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
168 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
169 inside the database for any incoming file attachment.
193
99ba212989cc Added entry related to MD5 integrity file checking
bgo-osimis
parents: 188
diff changeset
170
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
171 It is possible to ask Orthanc to check by itself whether some attachment
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
172 file was corrupted (i.e. to check whether the MD5 hash stored in the
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
173 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
174
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
175 $ 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
176
654
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
177 This MD5 may be different if errors occurred while the DICOM file was
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
178 initially written to the storage, or if the file contents were
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
179 tampered with afterwards.
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
180
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
181 You can retrieve the stored MD5 hash of a DICOM instance as follows::
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
182
e66534972166 dciodvfy
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
183 $ 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
184
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
185 Windows-specific issues
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
186 -----------------------
b12e2c1d9fed troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 15
diff changeset
187
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
188 * Under Windows, Orthanc creates the "OrthancStorage" folder, and
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
189 crashes with the error "**SQLite: Unable to open the database**":
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
190 Your directory name is either too long, or it contains special
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
191 characters. Please try and run Orthanc in a folder with a simple
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
192 name such as ``C:\Orthanc``.
55
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
193
903
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
194 * If you run Orthanc as a Windows service, and if you want to store
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
195 the Orthanc database (or the :ref:`Orthanc Web Viewer plugin
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
196 <webviewer>`) onto a shared network drive, you might encounter an
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
197 error ``boost::filesystem::status: The specified server cannot
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
198 perform the requested operation``. This probably means that the
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
199 ``SYSTEM`` account is not allowed to access the **mapped network
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
200 drive**. The easiest approach to this end consists in configuring
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
201 the Windows service to **run as user** (instead of the default
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
202 ``SYSTEM`` account), `as explained in this thread
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
203 <https://groups.google.com/g/orthanc-users/c/axrJfgA-Enk/m/Zeg3iUPOAwAJ>`__
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
204 on the Orthanc Users forum (cf. `additional reference
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
205 <https://docs.microfocus.com/SM/9.61/Hybrid/Content/serversetup/tasks/configure_the_service_manager_service_to_run_as_a_windows_user.htm>`__
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
206 elsewhere on Internet).
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
207
55
de283c29c92f not enough memory
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 44
diff changeset
208 * If **Orthanc crashes when handling one large DICOM file**, this most
1004
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
209 probably indicates a memory allocation error. Indeed, some
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
210 precompiled `official Windows binaries
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
211 <https://orthanc.uclouvain.be/downloads/windows-32/orthanc/index.html>`__
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
212 are compiled using a 32bit compiler. As a consequence, Orthanc only
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
213 has access to less than 4GB of RAM. If this is an important
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
214 limitation for you, precompiled command-line versions of Orthanc for
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
215 Windows 64bit are `also available
17bf6fafb884 added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
216 <https://orthanc.uclouvain.be/downloads/windows-64/orthanc/index.html>`__.
659
a37ac06ec2fc windows folder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 656
diff changeset
217
a37ac06ec2fc windows folder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 656
diff changeset
218 * Avoid installing Orthanc, its database or its storage area in
a37ac06ec2fc windows folder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 656
diff changeset
219 folders whose names contain **spaces or special characters**.
902
7f30e05a3319 note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 755
diff changeset
220
7f30e05a3319 note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 755
diff changeset
221 * 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
222 enabled, you might have to change your ``PATH`` environment variable
903
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
223 for Orthanc to **find the Python DLL**. The easiest approach to this
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
224 end consists in configuring the Windows service to **run as user**
902
7f30e05a3319 note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 755
diff changeset
225 (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
226 thread
7f30e05a3319 note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 755
diff changeset
227 <https://groups.google.com/g/orthanc-users/c/axrJfgA-Enk/m/Zeg3iUPOAwAJ>`__
903
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
228 on the Orthanc Users forum (cf. `additional reference
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
229 <https://docs.microfocus.com/SM/9.61/Hybrid/Content/serversetup/tasks/configure_the_service_manager_service_to_run_as_a_windows_user.htm>`__
25bbeb754420 note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 902
diff changeset
230 elsewhere on Internet).