diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..0cf72a69a --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8 -*- + +============================ +Glossary of Tahoe-LAFS Terms +============================ + + +.. glossary:: + + `Foolscap `_ + an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted + + storage server + a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations + + storage service + a Python object held in memory in the storage server which provides the implementation of the storage protocol + + introducer + a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers + + :ref:`fURLs ` + a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol + (the storage service is an example of such an object) + + :ref:`NURLs ` + a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap + + swissnum + a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service + + lease + state associated with a share informing a storage server of the duration of storage desired by a client + + share + a single unit of client-provided arbitrary data to be stored by a storage server + (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached) + + bucket + a group of one or more immutable shares held by a storage server and having a common storage index + + slot + a group of one or more mutable shares held by a storage server and having a common storage index + (sometimes "slot" is considered a synonym for "storage index of a slot") + + storage index + a 16 byte string which can address a slot or a bucket + (in practice, derived by hashing the encryption key associated with contents of that slot or bucket) + + write enabler + a short secret string which storage servers require to be presented before allowing mutation of any mutable share + + lease renew secret + a short secret string which storage servers required to be presented before allowing a particular lease to be renewed diff --git a/docs/index.rst b/docs/index.rst index 0335d5e8b..4dc7e41e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,8 @@ preserving your privacy and security. anonymity-configuration known_issues + glossary + .. toctree:: :maxdepth: 1 :caption: Tahoe-LAFS in Depth diff --git a/docs/specifications/http-storage-node-protocol.rst b/docs/specifications/http-storage-node-protocol.rst index db400fb2b..74d8dd8e1 100644 --- a/docs/specifications/http-storage-node-protocol.rst +++ b/docs/specifications/http-storage-node-protocol.rst @@ -16,53 +16,53 @@ The Tahoe-LAFS client will also need to change but it is not expected that it wi Glossary -------- -.. glossary:: +Foolscap + an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted - `Foolscap `_ - an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted +storage server + a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations - storage server - a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations +storage service + a Python object held in memory in the storage server which provides the implementation of the storage protocol - storage service - a Python object held in memory in the storage server which provides the implementation of the storage protocol +introducer + a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers - introducer - a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers +:ref:`fURLs ` + a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol + (the storage service is an example of such an object) - :ref:`fURLs ` - a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol - (the storage service is an example of such an object) +:ref:`NURLs ` + a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap - :ref:`NURLs ` - a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap +swissnum + a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service - swissnum - a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service +lease + state associated with a share informing a storage server of the duration of storage desired by a client - lease - state associated with a share informing a storage server of the duration of storage desired by a client +share + a single unit of client-provided arbitrary data to be stored by a storage server + (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached) - share - a single unit of client-provided arbitrary data to be stored by a storage server - (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached) +bucket + a group of one or more immutable shares held by a storage server and having a common storage index - bucket - a group of one or more immutable shares held by a storage server and having a common storage index +slot + a group of one or more mutable shares held by a storage server and having a common storage index + (sometimes "slot" is considered a synonym for "storage index of a slot") - slot - a group of one or more mutable shares held by a storage server and having a common storage index - (sometimes "slot" is considered a synonym for "storage index of a slot") +storage index + a 16 byte string which can address a slot or a bucket + (in practice, derived by hashing the encryption key associated with contents of that slot or bucket) - storage index - a 16 byte string which can address a slot or a bucket - (in practice, derived by hashing the encryption key associated with contents of that slot or bucket) +write enabler + a short secret string which storage servers require to be presented before allowing mutation of any mutable share - write enabler - a short secret string which storage servers require to be presented before allowing mutation of any mutable share +lease renew secret + a short secret string which storage servers required to be presented before allowing a particular lease to be renewed - lease renew secret - a short secret string which storage servers required to be presented before allowing a particular lease to be renewed +Additional terms related to the Tahoe-LAFS project in general are defined in the :doc:`../glossary` The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" diff --git a/newsfragments/4116.documention b/newsfragments/4116.documention new file mode 100644 index 000000000..0de46138d --- /dev/null +++ b/newsfragments/4116.documention @@ -0,0 +1 @@ +Add a global Sphinx generated glossary. Link the static GBS glossary to the global glossary. \ No newline at end of file