changeset 1083:e1f7f1e2d148

document AWS_EC2_METADATA_DISABLED
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 25 Jun 2024 12:54:16 +0200
parents 202b378001f0
children 337bbecf74c0
files Sphinx/source/plugins/object-storage.rst
diffstat 1 files changed, 26 insertions(+), 18 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/plugins/object-storage.rst	Tue Jun 18 13:45:39 2024 +0200
+++ b/Sphinx/source/plugins/object-storage.rst	Tue Jun 25 12:54:16 2024 +0200
@@ -10,19 +10,20 @@
 -------------
 
 Release notes are available `here
-<https://orthanc.uclouvain.be/hg/orthanc-object-storage/file/default/NEWS>`__ 
-   
+<https://orthanc.uclouvain.be/hg/orthanc-object-storage/file/default/NEWS>`__.
+
 Introduction
 ------------
 
-These 3 plugins enable storing the Orthanc files in `Object Storage <https://en.wikipedia.org/wiki/Object_storage>`__
-at the 3 main Cloud providers: `AWS <https://aws.amazon.com/s3/>`__, 
-`Azure <https://azure.microsoft.com/en-us/services/storage/blobs/>`__ & 
-`Google Cloud <https://cloud.google.com/storage>`__
+These 3 plugins enable storing the Orthanc files into `object storage
+<https://en.wikipedia.org/wiki/Object_storage>`__ at the 3 public
+cloud providers: `AWS <https://aws.amazon.com/s3/>`__, `Azure
+<https://azure.microsoft.com/en-us/services/storage/blobs/>`__, and
+`Google Cloud <https://cloud.google.com/storage>`__.
 
-Storing Orthanc files in object storage and your index SQL in a 
-managed database allows you to have a stateless Orthanc that does
-not store any data in its local file system which is highly recommended
+Storing Orthanc files in object storage and your index SQL in a
+managed database allows you to have a stateless Orthanc that does not
+store any data in its local file system, which is highly recommended
 when deploying an application in the cloud.
 
 
@@ -39,8 +40,9 @@
 
 These plugins are used to interface Orthanc with commercial and
 proprietary cloud services that you accept to pay. As a consequence,
-the Orthanc project usually doesn't freely update them or fix them unless
-the requester purchases a support contract e.g. at `Orthanc Team <https://orthanc.team>`__.
+the Orthanc project usually doesn't freely update them or fix them
+unless the requester purchases a support contract, e.g., at `Orthanc
+Team <https://orthanc.team>`__.
 
 Although you are obviously free to compile these plugins by
 yourself (instructions are given below), purchasing such support
@@ -91,6 +93,12 @@
 The **UseTransferManager** configuration is used to select the `Transfer Manager <https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/examples-s3-transfermanager.html>`__ mode in the AWS SDK client.
 This option was introduced in version 2.3.0.  If set to false (default value), the default "object" mode is used.
 
+**Important:** On Microsoft Windows, it is recommended to set the
+environment variable ``AWS_EC2_METADATA_DISABLED`` to ``true`` to
+speed up the initialization of the plugin. The reasons are explained
+in the `AWS official documentation
+<https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-envvars.html>`__.
+
 
 .. _minio:
   
@@ -209,7 +217,7 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When the ``HybridMode`` is set to ``WriteToFileSystem``, it is sometimes useful to move old files
-to the object-storage for long term archive or to `pre-fetch` files from object-storage to file
+to the object-storage for long term archive or to "pre-fetch" files from object-storage to file
 system for improved performances e.g when before opening the study in a viewer.
 
 When the ``HybridMode`` is set to ``WriteToObjectStorage``, it is useful to move file from the
@@ -236,12 +244,12 @@
 The **StorageStructure** configuration allows you to select the way objects are organized
 within the storage (``flat`` or ``legacy``).  
 Unlike the traditional file system in which Orthanc uses 2 levels
-of folders, object storages usually have no limit on the number of files per folder and 
+of folders, an object storage usually has no limit on the number of files per folder and 
 therefore all objects are stored at the root level of the object storage.  This is the
-default ``flat`` behaviour.  Note that, in the ``flat`` mode, an extension `.dcm` or `.json`
+default ``flat`` behavior.  Note that, in the ``flat`` mode, an extension ``.dcm`` or ``.json``
 is added to the filename which is not the case in the legacy mode.
 
-The ``legacy`` behaviour mimics the Orthanc File System convention.  This is actually helpful
+The ``legacy`` behavior mimics the Orthanc File System convention.  This is actually helpful
 when migrating your data from a file system to an object storage since you can copy all the file
 hierarchy as is.
 
@@ -332,7 +340,7 @@
 
 The format of data stored on disk is therefore the following:
 
-- **VERSION HEADER**: 2 bytes: identify the structure of the following data currently `A1`
+- **VERSION HEADER**: 2 bytes: identify the structure of the following data currently ``A1``
 - **MASTER KEY ID**: 4 bytes: a numerical ID of the KEK that was used to encrypt the DEK
 - **EIV**: 32 bytes: IV used by DEK for data encryption; encrypted by KEK
 - **EDEK**: 32 bytes: the DEK encrypted by the KEK.
@@ -348,11 +356,11 @@
 
   openssl rand -base64 -out /tmp/test.key 32
 
-Each key must have a unique id that is a uint32 number.
+Each key must have a unique id that is a ``uint32`` number.
 
 .. highlight:: json
 
-Here's a sample configuration file of the `StorageEncryption` section of the plugins::
+Here's a sample configuration file of the ``StorageEncryption`` section of the plugins::
 
   {
     "GoogleCloudStorage" : {