To run a local testnet, you’ll need to download or build the SAFE Vault binary and modify or create the following config files which need to exist in the same folder as the binary:
safe_vault.crust.config
safe_vault.routing.config
safe_vault.vault.config
Download SAFE Vault
Downloading the latest prebuilt binary is the simplest way to get started. This will include the required config files, but they will need to be modified to include some developer options as detailed below.
Build SAFE Vault
If you want to try building the vault binary yourself, then you need to have Git and the latest stable release of Rust installed. If you don’t, see Installing Git and rustup to install these.
-
Clone the repository:
git clone https://github.com/maidsafe/safe_vault.git --depth 1 -
Build SAFE Vault
cd safe_vault cargo build --release
This should produce the SAFE Vault binary in the folder safe_vault/target/release. It will be called safe_vault or safe_vault.exe depending on your platform. This folder is where you should also create the config files.
Example contents for safe_vault.crust.config
{
"hard_coded_contacts": [],
"force_acceptor_port_in_ext_ep": false,
"dev": {
"disable_external_reachability_requirement": true
}
}
Normally a vault is required to be able to allow a remote vault to connect to it; i.e. it must pass the “external reachability check”. For running a local testnet where all vaults are on the same machine or LAN, not only is this check useless, it could well fail since many routers don’t support hairpinning. Setting disable_external_reachability_requirement to true disables that check.
Further details on all Crust config options can be found in Crust’s config_handler.rs.
Example contents for safe_vault.routing.config
{
"dev": {
"allow_multiple_lan_nodes": true,
"disable_client_rate_limiter": true,
"disable_resource_proof": true,
"min_section_size": 5
}
}
Currently, we disallow more than one vault on a single LAN or machine. To disable this restriction, set allow_multiple_lan_nodes to true.
When a vault acts as a proxy for one or more clients, it limits the number and size of requests that it’ll forward on their behalf. To remove this limitation, set disable_client_rate_limiter to true. Setting this to true also allows a proxy to act on behalf of multiple clients with the same IP address, whereas this would not normally be allowed.
When a new vault connects to the network, each peer from the section it’s joining sends it a resource proof challenge. The challenge involves the new vault doing process-heavy work and sending a large message in response to confirm its upload capability. After a lengthy delay (several minutes) the peers all vote on whether to accept the new vault or not, and only if a quorum of positive votes are accumulated is the new vault allowed to join. If disable_resource_proof is set to true, the new vault is sent a challenge which involves minimal effort, time and traffic and the existing peers don’t delay their votes, enabling new vaults to join very much faster.
The network is comprised of sections of vaults, grouped together by IDs which are close to each other. These sections need to be comprised of a minimum number of vaults, currently defined as 8. Data is replicated across this number of vaults. This figure can be adjusted via the optional min_section_size field. As this figure reduces, the risk of data-loss increases (as there are fewer copies of each chunk of data). However, increasing this figure will increase the burden on each vault in terms of storage used, traffic sent and received, and network connections being maintained.
Further details on all Routing config options can be found in Routing’s config_handler.rs.
Example contents for safe_vault.vault.config
{
"dev": {
"disable_mutation_limit": true
}
}
Currently, clients are only allowed a limited number of requests to mutate (store, modify or delete) data on the network. To remove this limitation, set disable_mutation_limit to true.
Further details on all SAFE Vault config options can be found in Vault’s config_handler.rs.
Set up logging
While the vault runs it can generate log messages if required. There are five levels of log message. From most severe to least these are: error, warning, info, debug and trace. By default, only error-level messages are output to the console.
You can modify the logging behaviour either via an environment variable or via a config file. The env var is probably simpler, but the config file supports more options. If you specify a certain level, that level and all those more severe will be output. E.g. for info-level logging you will get info, warning and error-level output.
Logging via an environment variable
You can set the modules and log-levels required in the env var RUST_LOG. For example (on Windows) to enable logging for all modules at info-level:
set RUST_LOG=info
To only log Crust messages at debug-level:
set RUST_LOG=crust=debug
To log Crust at debug-level, and Routing (including stats messages) and Vault at trace-level:
set RUST_LOG=crust=debug,routing,routing_stats,safe_vault=trace
For further details on using RUST_LOG, see the docs for the env_logger crate.
Logging via a config file
You can similarly affect what is logged by creating a file named log.toml in the same folder as the vault binary. This also allows you to adjust the actual contents and format of the individual log messages, and furthermore to choose to output to the console, or a logfile, or both.
For example, the following log.toml would cause all info-level messages to be logged to the console, and would write debug-level Crust messages and trace-level Routing and Vault messages to a logfile in the current dir with the name Vault-<timestamp>.log:
[appenders.async_console]
kind = "async_console"
pattern = "{({l}):1.1} {d(%y-%m-%d %H:%M:%S%.6f)} {m}\n"
[[appenders.async_console.filters]]
kind = "threshold"
level = "info"
[appenders.async_file]
kind = "async_file"
output_file_name = "Vault.log"
pattern = "{({l}):1.1} {d(%y-%m-%d %H:%M:%S%.6f)} [{M} #FS#{f}#FE#:{L}] {m}\n"
append = false
file_timestamp = true
[root]
level = "error"
appenders = ["async_console", "async_file"]
[loggers."crust"]
level = "debug"
[loggers."routing"]
level = "trace"
[loggers."routing_stats"]
level = "trace"
[loggers."safe_vault"]
level = "trace"
Be aware that if you run multiple instances of the same vault binary and you want more than one to log to a file, then the simplest approach is to set file_timestamp = true and ensure that you leave at least one second between starting any two vaults. This has the effect of adding a raw timestamp (in seconds) to the chosen filename; so you’ll end up with logfiles called e.g. Vault-1501614444.log, Vault-1501614446.log, Vault-1501614448.log, etc.
If you want to avoid using timestamped logfiles, you can instead copy the vault folder including the binary and config files to multiple different parent folders. Or you could update the output_file_name before starting each new vault.
Further details on using the log.toml config file can be found in the docs for the log4rs crate, the most useful being the details on patterns and files. Note that the examples there use YAML, whereas we only support the TOML format.
Run several vaults
With the config files mentioned above placed in the same folder as the vault binary, you should now be able to start multiple instances of the binary, either in multiple terminals on a single machine, or single instances on multiple machines on the same LAN, or a combination of these.
Note: The first vault must be run with the --first flag (or -f for short) so it knows there aren’t any peers to connect to.
You should run at least min_section_size instances of the vault binary before trying to connect any clients, since that’s the minimum number required to safely store any data (including client accounts) on the network. This value is currently set to 5 by default, but can optionally be changed via the min_section_size dev option of the Routing config file (see above).
Miscellaneous
Eventually the vault codebase will be updated to handle unexpected or malicious behaviour from their peers. However, until that’s in place, all vaults and clients connecting to a single testnet should use the same configuration options. An exception is that logging config files can all be different or omitted altogether.
Just make sure to use the same config files for all vaults and clients connecting to your testnet.
Just a quick question… I assume that applications should be built without 
