CLI Reference

This document goes through the command-line tools, describing how to perform specific tasks such as creating a key-value store, deploying and scaling a cluster, etc.

Introduction

Terminology

The memo command-line tools are composed of several binaries, each dealing with a specific resource or object.

A user represents the entity performing operations on files, directly or indirectly. Every user possesses an RSA key pair that is used to identify him/her. A user can create a network which represents the interconnection of computing resources that will compose the storage infrastructure. A silo is a storage resource, local or remote, that can be connected to a device to support part of the overall storage load.

Home

All the configuration files memo creates and uses are located in the $MEMO_HOME directory which is, by default, set to $HOME. More precisely, memo stores configuration files, cache files etc. in the directories $MEMO_HOME/.local/{state,share}/memo/filesystem following the XDG Base Directory Specification.

Please refer to the environment variables documentation should you want to specifically define where the configuration files, journal operations etc. are stored.

As an example, $MEMO_DATA_HOME references the directory that contains the configuration files such as user identities, network descriptors etc. The environment variable is, by default, set to $MEMO_HOME/.local/share/memo/filesystem/ and can be very easily changed by either modifying your shell configuration or by setting it manually:

$> export MEMO_DATA_HOME="/some/where/"

Nomenclature

All the command-line tools rely on the same terminology when it comes to options and arguments. As an example, most objects have modes named create, list, fetch, etc.

For more information on the modes and options provided by a binary, do not hesitate to rely on the ‑‑help option. Note that the help is relative to the options already provided.

For example, the help for memo user displays the general options available: export, create, import, list, etc.:

$> memo user --help
Usage: ./_build/macosx64/bin/memo user [MODE|--help]
memo user management utility.

Modes:
  create     Create a user
  delete     Delete local user
  export     Export local user
  hash       Get short hash of user's key
  import     Import local user
  fetch      Fetch users from https://beyond.infinit.sh
  list       List local users
  login      Login user to https://beyond.infinit.sh
  pull       Pull a user from https://beyond.infinit.sh
  push       Push a user from https://beyond.infinit.sh
  signup     Create and push a user to https://beyond.infinit.sh

Options:
  -h, --help                show this help message

Each mode of each binary has its own help as well. For example the help when invoking the ‑‑create mode of memo user shows the options associated with creating a user:

$> memo user create --help
Usage: memo user create [OPTIONS]
Create a user

Options:
  -h, --help                show this help message
      --compatibility-version arg  compatibility version to force
  -s, --script              suppress extraneous human friendly messages and use JSON output
  -a, --as arg              user to run commands as (default: alice)
  -n, --name arg            name of the user to create (default: alice)
      --description arg     user description
  -k, --key arg             RSA key pair in PEM format - e.g. your SSH key
  -e, --email arg           user email
      --fullname arg        user full name
  -P, --password arg        password to authenticate with https://beyond.infinit.sh
  -l, --ldap-name arg       user LDAP distinguished name
  -o, --output arg          file to write the user to
      --push-user           push user to https://beyond.infinit.sh
  -p, --push                push user to https://beyond.infinit.sh
      --full                include private key (do not use unless you understand the implications

Every command is structured the same way: invoke the memo binary with first the object type (user, volume, etc.) then the action/mode (e.g., create, pull, list, etc.), and then options and arguments (such as ‑‑name, ‑‑pull and so forth).

The name/identifier of the object on which you wish to operate can be specified through the ‑‑name option or simply by providing it outside of any option. As such both commands below are equivalent:

$> memo network create --name personal
$> memo network create personal

Doctor

The memo doctor mode provides an easy way to check the health of your local environment: configuration files, version of the software, networking capabilities etc. To run all available tests, the all option can be used.

$> memo doctor all
CONFIGURATION INTEGRITY:
[OK] Storage resources
[OK] Networks
[OK] Volumes
[OK] Drives
[OK] Leftovers

SYSTEM SANITY:
[OK] Username
[OK] Space left
[OK] Environment
[OK] Permissions
[OK] FUSE

CONNECTIVITY:
[OK] Connection to https://beyond.infinit.sh
[OK] Local interfaces
[OK] Nat
[OK] UPNP
[OK] Protocols

All good, everything should work.

Connectivity

To ensure that a client has the required networking access to use memo, the connectivity option runs several tests:

Ensure HTTPS access to the Hub.
Check connectivity with a remote server using TCP and UDP.
Check for UPnP availability.
Check if the host is behind a NAT.

Sanity

A system sanity check can be run using the sanity option. This will check things like folder permissions, amount of free space and if there are any memo environment variables set.

Integrity

To ensure that the local infrastructure descriptors are valid, the integrity option can be used. This will do things like check that networks used by volumes have been fetched and linked to, that the compatibility version of the networks work with the current binaries, etc.

Networking

Finally, doctor has a networking mode to test connectivity and transfer speed between nodes.

NOTE: For now, nodes must have a public IP address for the test to work.

Device A
$> memo doctor networking
Server mode (version: 0.9.2):

To perform tests, run the following command from another node:
$> memo doctor networking --tcp_port 55848 --utp_port 41275 --xored_utp_port 54723 --host <address_of_this_machine>

Device B
$> memo doctor networking --tcp_port 55848 --utp_port 41275 --xored_utp_port 54723 --host 127.0.0.1
Client mode (version: 0.9.2):
TCP:
  Upload:
    215ms for 5.2 MB (24.4 MB/sec)
  Download:
    219ms for 5.2 MB (23.9 MB/sec)
UTP:
  Upload:
    377ms for 5.2 MB (13.9 MB/sec)
  Download:
    293ms for 5.2 MB (17.9 MB/sec)
xored UTP:
  Upload:
    364ms for 5.2 MB (14.4 MB/sec)
  Download:
    299ms for 5.2 MB (17.5 MB/sec)

User

The memo user mode allows one to create a user identity, push it to the Hub so that it can be referenced by other users and perform other user based operations.

Create a user

A user is not much more than an RSA key pair that will be used to sign and encrypt data. The following creates a user, automatically generating a new RSA key pair.

Note that the name of the user is deduced from the system if you do not specify a name through the ‑‑name option or the $MEMO_USER environment variable.

$> echo $USER
alice
$> memo user create
Generating RSA keypair.
Locally generated user "alice".

You may want to specify the RSA key pair to use rather than generating a new one. You can use the ‑‑key option to reference a PEM-formatted RSA private key (e.g your SSH RSA key) and memo will create a user identity based on it.

$> memo user create --name alice --key ~/.ssh/id_rsa
Key passphrase: ********
Locally generated user "alice".

WARNING: The user identity file is the equivalent of an SSH key file and must therefore be kept private at all times.

To register on the Hub, you can either use the push option when creating your user, push the user once it has been created locally or sign up directly on the Hub.

Push an existing user to the Hub

To push an existing user, simply invoke infinit user with the push mode. You can also specify an optional email address using ‑‑email but needless to say that this email address will never be shared with third parties and will solely be used for memo to communicate news of its file storage platform.

IMPORTANT: Given the critical nature of the user identity, we strongly advise you to read the Log in on another device section in order to completely understand the ramifications of the options used when pushing your user.

$> memo user push --name alice --fullname "Alice"
Remotely saved user "alice".

Create and push user on the Hub

Unfortunately, since names are unique, your user name may already be taken on the Hub, in which case the operation will fail. The action signup has been introduced to overcome this problem, performing the equivalent of create --push atomically, making sure that the user is created locally and remotely at once.

We advise users to sign up to the Hub before performing other operations to avoid complications:

$> memo user signup --name alice --fullname "Alice"
Generating RSA keypair.
Remotely saved user "alice".

Fetch a user

One can very easily fetch the public identity of another user through the fetch mode:

$> memo user fetch --name bob
Fetched user "bob".

List users

The list of users kept locally can contain both user identities that you created and therefore own as well as public identities of users that you fetched from the Hub for instance.

$> memo user list
alice: public/private keys
bob: public key only

Pull a user

To remove a user from the Hub, you can use the pull mode. The ‑‑name option specifies which user to pull while the ‑‑as option specifies which user should sign the pull request. Currently a user can only pull themself but in the future there will be the concept of administrator users who can pull other users.

$> memo user pull --as alice --name --alice
Remotely deleted user "alice".

To pull all objects that the user has pushed to the Hub along with the user itself, you can specify the ‑‑purge option:

$> memo user pull --as alice --name --alice --purge
Remotely deleted user "alice".

Delete a user

Users can be locally deleted using the delete mode. If the user has a private key, you will be prompted before the user is deleted as losing a user's public key will mean that you can no longer perform actions as that user. This includes pulling the user or any objects they have pushed to the Hub. To avoid being prompted, the ‑‑force option can be used.

$> memo user delete --name alice
WARNING: The local copy of the user’s private key will be removed.
WARNING: You will no longer be able to perform actions on the Hub
WARNING: for this user.

Confirm the name of the user you would like to delete: alice
Locally deleted user "alice".

To be symmetric with the ‑‑push option of the create mode, the delete mode is provided with a ‑‑pull option. This will remove the user both on the Hub and locally.

$> memo user delete --as alice --name alice --pull
WARNING: The local copy of the user’s private key will be removed.
WARNING: You will no longer be able to perform actions on the Hub
WARNING: for this user.

Confirm the name of the user you would like to delete: alice
Remotely deleted user "alice".
Locally deleted user "alice".

There is also the option ‑‑purge to locally remove all objects created by the user which can be combined with pull to remove all objects owned by the user from the Hub.

Credentials

The memo credentials binary manages the credentials for your cloud services. Cloud services, such as Amazon Web Services, Google Cloud Storage and Dropbox, can be used to add storage to your networks. memo considers these cloud services as basic and unprivileged datastores that are used to store blocks of encrypted data.

_NOTE: Because this binary requires the Hub for some types of credentials (such as Dropbox and Google), you may need to register your user on the Infinit Hub. For more information, please refer to the User section, more specifically how to Sign up on the Hub._

Add credentials

The basic process for adding credentials consists in using the add option as shown in the example below with Amazon Web Services:

$> memo credentials add --aws --name s3-user
Please enter your AWS credentials
Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: ****************************************
Locally stored AWS credentials "s3-user".

However, the procedure to follow differs with every cloud service. It is therefore advised to read the guide associated with the cloud service you intend to connect:

NOTE: Do not hesitate to vote for and/or request the cloud services you would like to be supported in the future.

List credentials

At any point, you can list your local credentials using the list option:

$> memo credentials list
AWS:
  AKIAIOSFODNN7EXAMPLE: s3-user
GCS:
  alice@company.com: Alice

Delete credentials

Credentials can be locally removed using the delete mode:

$> memo credentials delete --aws --name s3-user
Locally deleted credentials "s3-user".

Silo

The memo silo mode allows for the definition of silos. Such silos can be local — storing blocks of data on a locally available file system — or remote in which case the blocks of data are stored through a cloud service API for instance.

Note that silos are device-specific. As such, resources cannot be pushed to the Hub since they only live locally.

Create a silo

To create a silo, simply specify the create option along with the type of the silo. In the example below, a silo is created on top of an existing local file system by storing the blocks of encrypted data in a specific directory specified that can be specified through the ‑‑path option:

$> memo silo create filesystem --capacity 2GB --name local
Created storage "local".

However, the process differs depending on the nature of the silo. Please follow the guide that is specific to the type of storage you want to create:

NOTE: Do not hesitate to vote for and/or request the types of storage backends that you would like to see supported in the future.

Delete a silo

You can locally delete a silo using the delete mode. For filesystem silos, you can clear their contents using the ‑‑clear-content option.

Using ‑‑purge will unlink all networks that use the storage locally.

Network

With the memo network mode you are able to create overlay networks, configure the way the distributed hash table behaves and much more.

Create a network

The example below creates a network named "cluster" which aggregates the silos controlled by the users involved in this network.

The network can be configured depending on the requirements of the storage infrastructure the administrator is setting up. For instance, the number of computing devices could be extremely small, the owners of those computers could be somewhat untrustworthy or their machines could be expected to be turned on and off throughout the day. To cater for this the network parameters can be tuned: the overlay's topology, the replication factor, the fault tolerance algorithm, etc.

The following creates a storage network, relying on the default overlay network with a replication factor of 3. In addition, the administrator decides to contribute two silos to the network on creation.

$> memo network create --as alice --replication-factor 2 --storage local --storage s3 --name cluster
Locally created network "alice/cluster".

The overlay network (i.e the algorithm connecting the nodes together) can be configured. Below are listed some of the overlay networks available:

Kalimero: Simple test overlay supporting only one node.
Kelips: Overlay with support for node churn. The k argument specifies the number of groups to use, each group being responsible for 1/kth of the files. See the reference paper "Kelips: Building an Efficient and Stable P2P DHT through Increased Memory and Background Overhead" for more information.
Kouncil: Fully connected overlay that stores the whole block address book in memory, and broadcast updates to all nodes when a new block is created.

An administrator can be set for the network. This allows the given user either read or read/write permissions for all files in all volumes on the created network. To enable this feature, the ‑‑admin-r USER or ‑‑admin-rw USER arguments respectively.

Push a network

You can now push a network onto the Hub for other users to retrieve it. Note that the easiest way is always to append the push option to the network creation command to perform both the creation and publication actions at once.

As with the other utilities, you can otherwise push the network to the Hub with the push option:

$> memo network push --as alice --name cluster
Remotely saved network "alice/cluster".

You can also manipulate networks without relying on the Hub. Please refer to the ‑‑export and ‑‑import options in this case.

List the networks

You can list the networks that you have locally using the list mode. Do not forget that you may need to fetch the networks from the Hub in order to be up to date:

$> memo network fetch --as alice
Fetched networks for user "alice".
$> memo network list
alice/cluster

Link a device to a network

Before a network can be connected to, it must be linked to a user on the device. When creating the network with the create option, the network is linked automatically.

Upon linking to (or creating) the network, storage can be contributed to it using the ‑‑storage argument. This will be demonstrated below.

There are two distinct cases for linking networks which depend on the given user's relation to the network: the user is the owner on another device or the user is an invitee.

As the owner

As the owner of the network, the system automatically recognizes you and allows you to link any of your devices to the network. The process in this case is straightforward.

In the example below, Alice connects one of her other devices and contributes storage capacity from her personal Network-Attached Storage (NAS).

$> memo network link --as alice --name cluster --storage nas
Linked device to network "alice/cluster".

NOTE: Keep in mind that the action of linking a device to a network must only be performed once per user on every new device.

As an invitee

In this case, you should have received, through the Hub or manually, an invitation to join a network created by someone else. Such invitations are called passports and allow users to link their devices to the network they've been allowed to join.

In order to link a device to a network, you must first retrieve its descriptor. This network descriptor can be fetched from the Hub through a single command:

$> memo network fetch --as bob --name alice/cluster
Fetched network "alice/cluster".

You now have both the network descriptor and a passport locally allowing you to link new devices to it. Let's link Bob's current device to Alice's "cluster" network. Note that one can decide to contribute additional storage capacity through the ‑‑storage option.

$> memo network link --as bob --name alice/cluster
Linked device to network "alice/cluster".

NOTE: This process must be performed on each new device, proving that the user has indeed been allowed to join the network (via the passport) and that this device belongs to the user.

Run a network

Running a network means launching the memo software to act as a node in the storage network, also known as a "server". For a node to act as a server, it must contribute some storage capacity.

If you want your node to also provide a POSIX-compliant file system interface, please consider running/mounting a volume.

In order to run a network, just use the option run. Note that the ‑‑publish option tells the binary to rely on the Hub to ease the process of connecting to the network by providing you with the endpoint of bootstrap nodes while publishing your own endpoint for other nodes to find you as well:

$> memo network run --as alice --name cluster --publish
Running network "alice/cluster".
Fetched endpoints for "alice/cluster".
Remotely pushed endpoints for "alice/cluster".
...

Inspect a running network

Once a network is running, you can easily get information about it using the ‑‑inspect option. This information includes things such as which peers are connected to, data redundancy information and the type of consensus used.

$> memo network inspect --name alice/company --all
{
    "consensus" : {
        "node_timeout" : "600s",
        "type" : "paxos"
    },
    "overlay" : {
        "id" : "0x0000000000000000000000000000000000000000000000000000000000000000",
        "type" : "kouncil"
    },
    "peers" : [
        {
            "endpoints" : [
                "10.0.0.1:45602",
            ],
            "id" : "0x0000000000000000000000000000000000000000000000000000000000000001"
        },
        {
            "endpoints" : [
                "10.0.0.2:34458",
            ],
            "id" : "0x0000000000000000000000000000000000000000000000000000000000000002"
        }
    ],
    "protocol" : "all",
    "redundancy" : {
        "desired_factor" : 3,
        "type" : "replication"
    }
}

Upgrade a network

Every node, no matter the version of its memo software, will always run in a compatibility mode defined by the version of the network. As such, assuming all the clients and servers are operating in version 0.5.4 while the network is configured in 0.3.0, all the nodes would behave as if running the version 0.3.0.

Upgrading a network, say from 0.3.0 to 0.5.0, allows nodes to benefit from the functionality introduced between those versions. The process of upgrading a network goes through several steps, from updating the network descriptor to distributing it to the clients and servers to finally restarting the nodes to take the new descriptor into account.

The complete procedure is detailed in the Upgrading a network guide.

Pull a network

Networks can be pulled from the Hub using the pull mode. If the ‑‑purge option is used, all volumes and drives which rely on the given network and belong to the user will be pulled as well.

Delete a network

To delete a network locally, the delete mode is used. This can be used in conjunction with the ‑‑purge and ‑‑pull options to, respectively, delete volumes and drives that depend on the network locally and pull them from the Hub. Note only volumes and drives owned by the user can be pulled from the Hub.

Network administrators

Networks can be assigned administrators who have either read only or read/write access to all blocks (and thus implicitly files and folders) stored on a network. As memo is completely decentralized there are two limiting factors: all users must have the same network descriptor and changes to administrators are not retroactive.

On creation of a network, individual administrators can be added using the ‑‑admin-r and ‑‑admin-rw arguments as shown in the example that follows:

$> memo network create --as alice --storage local --admin-r bob --name administrated-cluster --push
Locally created network "alice/administrated-cluster".
Remotely saved network "alice/administrated-cluster".

Once a network has been created, administrator users and groups can be added using the update action. Note that as groups are stored internally in the network DHT, you will need to have created and mounted a volume on the network to add an administrator group.

$> memo network update --as alice --admin-rw charlie @managers --mountpoint /path/to/mounted/volume/on/network --push
Updated linked network "alice/administrated-cluster".
Updated network "alice/administrated-cluster".
Remotely updated "alice/adminstrated-cluster".
INFO: Changes to network admins do not affect existing data:
INFO: Admin access will be updated on the next write to each
INFO: file or folder.

IMPORTANT: All storage nodes and users who have already run the network will need to fetch the new network descriptor and relaunch the network. Changes to administrator rights occur on the next write to any given file or folder.

Similarly, administrators can be removed using the ‑‑admin-remove argument.

$> memo network update --as alice --admin-remove bob --mountpoint /path/to/mounted/volume/on/network --push
Updated linked network "alice/administrated-cluster".
Updated network "alice/administrated-cluster".
Remotely updated "alice/adminstrated-cluster".
INFO: Changes to network admins do not affect existing data:
INFO: Admin access will be updated on the next write to each
INFO: file or folder.

Passport

The memo passport mode is used to control which users are allowed to connect to a network, granting him/her the right to link devices, contribute silos etc.

Create a passport

To allow another user to join a network and link devices, you must issue a passport. In order to reference the user to invite, you first need to obtain his/her user public identity.

Let's say that you want to invite the user "bob" to your network. First you need to fetch his identity from the Hub (or retrieve it manually if operating without the Hub, see -export and import):

$> memo user fetch --as alice --name bob
Fetched user "bob".

The passport that you are about to create will be sealed, allowing only Bob to connect new devices to the network:

$> memo passport create --as alice --network cluster --user bob
Locally created passport "alice/cluster: bob".

You can restrict the network permissions given by a passport by creating it with the following options:

‑‑deny-write: Passport grants read-only access to the network. Note that this option supersedes the ACL of a volume and that a storage node with this flag will not be able to rebalance blocks.
‑‑deny-storage: Passport does not allow user to contribute any storage to the network.

Now that the passport has been created, read the Distribute a passport section to learn how to distribute it to the invited user.

List the passports

You can list both the passports you've created for other users to join your networks and the passports issued by other users for you to join their networks:

$> memo passport list --as alice
alice/cluster: bob

Distribute a passport

Once the passport has been locally created, you must distribute it to the invited user for him/her to be able to join your network.

The easiest way to do this is to rely on the Hub, by appending the push option when creating the passport; see the Create a passport section.

You can otherwise push a local passport by invoking the push action option as shown below:

$> memo passport push --as alice --network cluster --user bob
Remotely saved passport "alice/cluster: bob".

If you are using the pure decentralized environment i.e. without the Hub, you will need to manually export the passport and transmit it to the invited user in which case you should refer to the export and import options.

IMPORTANT: Be aware that the invited user will not be notified that there is a new passport for him/her to join your network. The invited user could detect this by fetching his/her passports and noticing a new one but that's about it. In order to speed things up, you should probably inform him/her through the medium of your choice: chat, email, carrier pigeon or else.

Receive a passport

You can fetch your passports from the Hub in order to refresh the local snapshots using the fetch option:

$> memo passport fetch --as bob
Fetched passports for user "bob"
$> memo passport list --as bob
alice/cluster: bob

NOTE: The memo passport mode also provides options to fetch all the passports for a specific user or for a specific network.

That's it, you will now be able to link devices to the networks these passports allow you to.

Delegate the creation of passports

The network administrator may not want to be the only user to be able to issue passports, because he is not always connected for instance. A special type of passport has been introduced to delegate the process of passport creation.

The process of delegation is performed in two steps. The first is to create the passport with the ‑‑allow-create-passport flag:

$> memo passport create --as alice --network cluster --user bob --allow-create-passport --push
Locally created passport "alice/cluster: bob".

The second is to register the user's public key.

IMPORTANT: This can only be done once you have created a volume on the network as you will be required to mount the volume and use the memo acl mode to register the user.

$> memo acl register --network cluster --user bob --path /path/to/mountpoint

Bob can now fetch the new passport, at which point he will in turn be able to issue passports for other users to connect to the network.

Access Control List

Having joined a volume does not mean that you have the required permissions to browse the files and directories in it. As with most file system, in order to access, edit and/or delete a file, the owner must first grant you the permission to do so.

Unlike other file systems, memo provides advanced decentralized (i.e. without relying on a centralized server) access control mechanisms that allow any user to manage permissions on his/her files and directories.

The owner of a volume is automatically granted access to its root directory. It is then his/her responsibility to manage the permissions on the root directory for other users to use the volume.

Note that most access control actions use POSIX mechanisms such as standard permissions and extended attributes. The memo acl mode can be considered as a wrapper on top of extended attributes which allows one to manipulate the ACL of an memo volume.

Grant/revoke access

In order to grant or revoke access to a file or directory, one uses the memo acl mode, providing the path to the object to manage and the permissions to apply.

The following grants Bob the permissions required to read and write the root directory of Alice's volume mounted to /mnt/shared/.

$> memo acl set --path /mnt/shared/ --mode rw --user bob

NOTE: The memo acl mode provides additional options to better manage hierarchical permissions. Do not hesitate to rely on the help to learn more.

Once the command has been run, Bob will be able to read and write files/directories in the root directory of Alice's "shared" volume.

Inheritance

ACL inheritance is a mechanism that sets the ACL of newly created files and directories to that of their parent directory. It can be enabled or disabled on a per-directory basis using the ‑‑enable-inherit and ‑‑disable-inherit options:

$> infint-acl set --path /mnt/shared --enable-inherit

If ACL inheritance is disabled, newly created files and directories can only be accessed by their owner. If enabled, all the ACLs set on the parent directory are copied to the new object, including the inheritance flag for directories.

World-readability/writability

By default, files and directories can only be read/written by users present in the object's ACLs. It is possible to flag a file/directory as world-readable (everyone can read it) or world-writable (everyone can modify it).

The chmod UNIX binary can be used to set this. The following example sets a file as world-readable before making it world-writable as well. The ls -l command displays a file as world-readable/write through the others category (the last three rwx indicators).

$> ls -l /mnt/shared/awesome.txt
-rw-------  1 alice  users     14B Jan 20 16:55 awesome.txt
$> chmod o+r /mnt/shared/awesome.txt
-rw----r--  1 alice  users     14B Jan 20 16:55 awesome.txt
$> chmod o+w /mnt/shared/awesome.txt
-rw----rw-  1 alice  users     14B Jan 20 16:55 awesome.txt

NOTE: The option ‑‑others-mode can also be used in the memo acl mode to set and list the permissions associated with 'everybody'.

List permissions

Every user with the volume descriptor and read permissions can consult the Access Control List (ACL) associated with a file system object:

$> memo acl list --path /mnt/shared/awesome.txt
/mnt/shared/awesome.txt:
     alice: rw (owner)
     bob: r

NOTE: To list permissions of files and folders on macOS to which you do not have access, you will need to execute the command with sudo. This will be fixed in a later release of memo.

POSIX mode

Since the memo access model is ACL based, the POSIX file mode as displayed by ls -l differs from what you might expect:

$> ls -l /mnt/shared/
total 64
drwx------  1 alice  staff     0B Jan 20 17:15 Engineering
-rw-------  1 alice  staff    14B Jan 20 16:59 awesome.txt

One must take into account that:

User and group IDs are set to the user who mounted the file system if he/she has read or write access to the file. Otherwise they are set to root. Changing them (using chown) has no effect.
User read/write access mode (u+r and u+w) are set according to the ACLs, properly reflecting what operations the user who mounted the file system is allowed to perform. Changing these flags has no effect.
User execute access mode can be set or cleared and is preserved. This flag is not ensured at the network level through cryptographic mechanisms. Instead, a flag is just set to indicate that the file is 'executable'.
Group modes are irrelevant and set to zero.
Others read/write access modes can be set to make the object readable/writable for all. See World-readability/writability for more information.

Create a group

memo supports the concept of groups i.e a collection of users. Such groups ease the process of access control management by allowing a user to re-reference groups of users.

Each group is identified by a unique name, and can be created by any user in the network. It stores a list of group members that can be users and other groups, resulting in hierarchical groups. A group's member list can be modified only by the users administrating the group. By default only the user who created it is the administrator of the group. Below is shown an example of group creation:

$> memo acl group --create --name marketing --path .

NOTE: The ‑‑path option must be provided for the memo acl to know which volume, hence network, you want the group to be created in. You can use the ‑‑path option to reference the volume's mountpoint or any of its files/folders.

From that point, it is very easy to display information on a group using the ‑‑show action:

$> memo acl group --show --name marketing --path .
{"admins":["alice"],"members":["@marketing","alice"]}

Once created, a group can be added to any object's ACLs using memo acl set. The process is the same as granting access to a user except that the group name must be prefixed with an '@' character:

$> memo acl set --mode rw --user @marketing --path /mnt/shared/awesome.txt

Add/remove group members

Any group administrator can add and remove members through the ‑‑add and ‑‑remove options. In the example below, Alice first adds Bob as a member of her Marketing group. Then, Alice creates a group named "marketing/tokyo" and adds it to her Marketing group.

$> memo acl group --name marketing --add-user bob --path .
$> memo acl group --create --name marketing/tokyo --path .
$> memo acl group --name marketing --add-group marketing/tokyo --path .

The "marketing/tokyo" group could also be added or removed using the ‑‑add or ‑‑remove option and a '@' prefix before the group name:

$> memo acl group --name --marketing --add @marketing/tokyo --path .

Add/remove group administrators

A group can be administered by multiple users at once, increasing the flexibility of the group concept a bit more. To add/remove administrator to a group, simply rely on the ‑‑add-admin and ‑‑remove-admin actions:

$> memo acl group --name marketing --add-admin bob --path .
$> memo acl group --show --name marketing --path .
{"admins":["alice","bob"],"members":["@marketing","alice","bob"]}

As before, administrators can be added and removed using the ‑‑add and ‑‑remove option with a '^' prefix:

$> memo acl group --name marketing --add ^bob --path .

Device

Log in on another device

You may wish to access your infrastructure from another machine. The critical nature of the user's identity (which is similar to an SSH key) makes this operation more complex than the others.

In a nutshell, one needs to re-create his/her memo environment with all the resources (users, networks, volumes, drives etc.) on the other computer. If you are using memo in a completely decentralized manner, then the operation of exporting all the objects manually and re-importing them on the other device will be familiar. If you have gotten used to the ease-of-use of the Hub, then we offer you two methods to transmit your user identity to another device.

Note that the preferred method when using the command-line tools should be to transmit the user identity to another device.

Store the user identity on the Hub

The easiest (but least secure) way to retrieve your user identity on another device is to activate a mode in which your private identity is kept on the Hub, encrypted with a key to protect it from potential intruders.

To activate this mode, you need to specify the ‑‑full option when signing up on the Hub, along with a password, as shown below. Note that the password can be provided in-line using the ‑‑password option or entered when prompted:

Device A
$> memo user signup --name alice --fullname Alice --full
Password: ********
Remotely saved user "alice".

Following this operation, one can login on another device very simply by invoking the ‑‑login option:

Device B
$> memo user login --name alice
Password: ********
Locally saved user "alice".

That's it, you can see by listing the local users that your private user identity has been retrieved:

Device B
$> memo user list
alice: public/private keys

NOTE: If you already registered your user on the Hub but would like to activate this login mode, you can remove your user from the Hub with the pull option and then re-push with the ‑‑full option along with a password.

Transmit user identity to another device

If you are uncomfortable with us keeping your user identity, there is another (preferred) way for you to transmit your user identity to another machine.

The method relies on the Hub as a temporary store for your user identity to be kept until it is retrieved on another device. If not retrieved after 5 minutes, the user identity will be removed from the Hub. The user identity is also encrypted with a key of your choice so that we cannot access it. In the future, a direct point-to-point method will be used to bypass the Hub altogether.

Device A
$> memo device transmit --as alice --user
Passphrase: ********
Transmitted user identity for "alice".
User identity on the Hub for: 297 seconds

Once the command has been launched, you have 5 minutes to retrieve the user identity on another device using the following command:

Device B
$> memo device receive --user --name alice
Passphrase: ********
Received user identity for "alice".

You can verify that the user has been saved locally by listing the local users:

Device B
$> memo user list
alice: public/private keys

Once retrieved, the user identity is removed from the Hub. Even though this method is not ideal, it is a fair compromise between security (short window of attack, encrypted with a unique key of your choosing etc.) and simplicity (two commands to invoke, no file to manually move around etc.).

Manually export/import the user identity

For users that either do not trust the two methods above or who are using a completely decentralized environment, there is another method which can be used. This requires exporting the full user identity, moving the file manually and finally re-importing it on the new device.

First, export the user identity to a file:

Device A
$> memo user export --name alice --full --output alice.user
WARNING: you are exporting the user "alice" including the private key
WARNING: anyone in possession of this information can impersonate that user
WARNING: if you mean to export your user for someone else, remove the --full flag
Exported user "alice".
$> cat alice.user
{"fullname":"Alice","id":"2J8reEAY","name":"alice","private_key":{"rsa":"MIIEp...M/w=="},"public_key":{"rsa":"MIIBC...DAQAB"}}

At this point, it is your responsibility to move the file to your other device, using SCP for instance. Re-creating the user entity the just requires an import:

Device B
$> memo user import --input alice.user
Imported user "alice".