github.com/sym3tri/etcd@v0.2.1-0.20140422215517-a563d82f95d6/Documentation/etcd-file-system.md (about)

     1  #Etcd File System
     2  
     3  ## Structure
     4  [TODO]
     5  ![alt text](./img/etcd_fs_structure.jpg "etcd file system structure")
     6  
     7  ## Node
     8  In **etcd**, the **node** is the base from which the filesystem is constructed.
     9  **etcd**'s file system is Unix-like with two kinds of nodes: file and directories.
    10  
    11  - A **file node** has data associated with it.
    12  - A **directory node** has child nodes associated with it.
    13  
    14  All nodes, regardless of type, have the following attributes and operations:
    15  
    16  ### Attributes:
    17  - **Expiration Time** [optional]
    18  
    19    The node will be deleted when it expires.
    20  
    21  - **ACL**
    22  
    23    The path to the node's access control list.
    24  
    25  ### Operation:
    26  - **Get** (path, recursive, sorted)
    27  
    28    Get the content of the node
    29      - If the node is a file, the data of the file will be returned.
    30      - If the node is a directory, the child nodes of the directory will be returned.
    31      - If recursive is true, it will recursively get the nodes of the directory.
    32      - If sorted is true, the result will be sorted based on the path.
    33  
    34  - **Create** (path, value[optional], ttl [optional])
    35  
    36    Create a file. Create operation will help to create intermediate directories with no expiration time.
    37      - If the file already exists, create will fail.
    38      - If the value is given, set will create a file.
    39      - If the value is not given, set will crate a directory.
    40      - If ttl is given, the node will be deleted when it expires.
    41  
    42  - **Update** (path, value[optional], ttl [optional])
    43  
    44    Update the content of the node.
    45      - If the value is given, the value of the key will be updated.
    46      - If ttl is given, the expiration time of the node will be updated.
    47  
    48  - **Delete** (path, recursive)
    49  
    50    Delete the node of given path.
    51      - If the node is a directory:
    52      - If recursive is true, the operation will delete all nodes under the directory.
    53      - If recursive is false, error will be returned.
    54  
    55  - **TestAndSet** (path, prevValue [prevIndex], value, ttl)
    56  
    57    Atomic *test and set* value to a file. If test succeeds, this operation will change the previous value of the file to the given value.
    58      - If the prevValue is given, it will test against previous value of
    59      the node.
    60      - If the prevValue is empty, it will test if the node is not existing.
    61      - If the prevValue is not empty, it will test if the prevValue is equal to the current value of the file.
    62      - If the prevIndex is given, it will test if the create/last modified index of the node is equal to prevIndex.
    63  
    64  - **Renew** (path, ttl)
    65  
    66    Set the node's expiration time to (current time + ttl)
    67  
    68  ## ACL
    69  
    70  ### Theory
    71  Etcd exports a Unix-like file system interface consisting of files and directories, collectively called nodes.
    72  Each node has various meta-data, including three names of the access control lists used to control reading, writing and changing (change ACL names for the node).
    73  
    74  We are storing the ACL names for nodes under a special *ACL* directory.
    75  Each node has ACL name corresponding to one file within *ACL* dir.
    76  Unless overridden, a node naturally inherits the ACL names of its parent directory on creation.
    77  
    78  For each ACL name, it has three children: *R (Reading)*, *W (Writing)*, *C (Changing)*
    79  
    80  Each permission is also a node. Under the node it contains the users who have this permission for the file referring to this ACL name.
    81  
    82  ### Example
    83  [TODO]
    84  ### Diagram
    85  [TODO]
    86  
    87  ### Interface
    88  
    89  Testing permissions:
    90  
    91  - (node *Node) get_perm()
    92  - (node *Node) has_perm(perm string, user string)
    93  
    94  Setting/Changing permissions:
    95  
    96  - (node *Node) set_perm(perm string)
    97  - (node *Node) change_ACLname(aclname string)
    98  
    99  
   100  ## User Group
   101  [TODO]