diff --git a/src/parsec_service/build_run.md b/src/parsec_service/build_run.md index c3dff36..17c360e 100644 --- a/src/parsec_service/build_run.md +++ b/src/parsec_service/build_run.md @@ -20,43 +20,41 @@ replaced by a subset of the features mentioned above, space or comma separated. test the TPM or PKCS check the [related guides](tests#testing-the-tpm-provider-using-the-software-tpm). -For the `DomainSocket` listener, the socket folder needs to be created: - -``````` -mkdir /tmp/parsec -``````` - On a real deployment (as explained in our [installation guide](install_parsec_linux.md)) specific -owners and permissions need to be set up on this folder. Those security settings will be checked by -the clients for them to make sure they are communicating with a trusted Parsec service. For testing -only, it is fine to keep the folder as it is. +owners and permissions need to be set up on multiple folders. Those security settings will be +checked by the clients for them to make sure they are communicating with a trusted Parsec service. +For testing only, it is fine to run Parsec from the current directory, have the key information +mappings in `./mappings` and the socket at `/tmp/parsec.sock`. The test configuration will make +those choices. -To build and run Parsec from source: +Having cloned the Parsec repository, to build and run from source using the Mbed Crypto provider and +the test configuration: ``````` -RUST_LOG=info cargo run --features mbed-crypto-provider +RUST_LOG=info cargo run --features mbed-crypto-provider -- -c e2e_tests/provider_cfg/mbed-crypto/config.toml ``````` `parsec` will then construct the service based on the configuration file and wait for clients. -Setting `RUST_LOG=info` on the command line is not needed if the log level was modified via the -configuration file. At the end of initialization, it should print `Parsec is ready` which means that it is ready to take -requests from clients. +requests from clients: -If the configuration file is not in the directory from which Parsec is run, its path must be passed -via a command-line argument: +``` +[INFO parsec] Parsec started. Configuring the service... +[INFO parsec_service::utils::service_builder] Creating a Mbed Crypto Provider. +[WARN parsec_service::front::domain_socket] Incorrect user. Parsec should be run as user parsec. Follow recommendations to install Parsec securely or clients might not be able to connect. +[INFO parsec] Parsec is ready. +``` -``````` -cargo run --features mbed-crypto-provider -- --config e2e_tests/provider_cfg/mbed-crypto/config.toml -``````` +The `WARN` log warns us that we are not following the secure installation practices which is fine as +this is for testing. From another terminal, it is now possible to execute the [end-to-end tests](tests#end-to-end-tests) on Parsec! ``````` cd e2e_tests -cargo test normal_tests +cargo test --features mbed-crypto-provider normal_tests ``````` ## Killing Parsec diff --git a/src/parsec_service/install_parsec_linux.md b/src/parsec_service/install_parsec_linux.md index 9b7d220..3acdc73 100644 --- a/src/parsec_service/install_parsec_linux.md +++ b/src/parsec_service/install_parsec_linux.md @@ -12,19 +12,39 @@ can be a space or comma-separated subset of: `mbed-crypto-provider`, `pkcs11-pro `tpm-provider`. Choose the providers you want to install depending on what is available on the platform. -Create the Parsec socket directory. +## From an admin user with privileges + +Create the `parsec` user. ``` -mkdir /tmp/parsec +sudo useradd -m parsec +sudo passwd parsec ``` -Create the `parsec-clients` group and set the correct permissions on the socket folder. Mutually -trusted Parsec Clients will need to be in that group. +Create the following Parsec directories, with good permissions: + +- `/var/lib/parsec` for storing persistent data like the `mappings` folder. +- `/etc/parsec` to contain the configuration file. +- `/usr/libexec/parsec` to contain the `parsec` executable binary file. +- `/run/parsec` to contain the socket file. The `parsec-clients` group needs to be created. Mutually + trusted Parsec Clients will need to be in that group. + +Commands: ``` +sudo mkdir /var/lib/parsec +sudo chown parsec /var/lib/parsec +sudo chmod 700 /var/lib/parsec +sudo mkdir /etc/parsec +sudo chown parsec /etc/parsec +sudo chmod 700 /etc/parsec +sudo mkdir /usr/libexec/parsec +sudo chown parsec /usr/libexec/parsec +sudo chmod 700 /usr/libexec/parsec sudo groupadd parsec-clients -sudo chown :parsec-clients /tmp/parsec -sudo chmod 750 /tmp/parsec +sudo mkdir /run/parsec +sudo chown parsec:parsec-clients /run/parsec +sudo chmod 750 /run/parsec ``` For example, adding the imaginary `parsec-client-1` user to the `parsec-clients` group: @@ -34,12 +54,13 @@ sudo usermod -a -G parsec-clients parsec-client-1 ``` Users just added to that group might need to log-out and log-in again to make sure the change apply. +They can also try the `newgrp` command with no parameters to re-initialize their environment. + +## From the parsec user -Create and log in to a new user named `parsec`. +Log in to `parsec`. ``` -sudo useradd -m parsec -sudo passwd parsec su --login parsec ``` @@ -47,19 +68,22 @@ Depending on which features of Parsec the `parsec` user is going to use, it migh more privileges in order to access some resources on the system. Refer to the [Providers](providers.md) page for more information. -In its home directory, pull and install Parsec as a daemon. If a Rust toolchain is not available -widely on the system, it will need to be [installed](https://www.rust-lang.org/tools/install) for -that specific user. +In its home directory, clone and compile Parsec. If a Rust toolchain is not available widely on the +system, it will need to be [installed](https://www.rust-lang.org/tools/install) for that specific +user. + +Below is an example with Parsec 0.5.0, update with the version you want! ``` -cargo install parsec-service --features $DESIRED_FEATURES +git clone --branch 0.5.0 https://github.com/parallaxsecond/parsec +cargo build --manifest-path parsec/Cargo.toml --features $DESIRED_FEATURES --release +cp parsec/target/release/parsec /usr/libexec/parsec ``` -Copy and adapt the [configuration](configuration.md) you want to use. For a secure deployment, make -sure to activate the `log_error_details` option and to use a `trace` log level. +Adapt and copy the [configuration](configuration.md) you want to use. ``` -cp parsec/config.toml config.toml +cp parsec/config.toml /etc/parsec/config.toml ``` Install the systemd unit files and activate the Parsec socket. @@ -71,27 +95,31 @@ systemctl --user enable parsec systemctl --user start parsec ``` -`parsec-clients` users can now use Parsec! You can test it (having logged in a `parsec-clients` -user) going inside the `parsec/e2e_tests` directory and: +Check the Parsec logs with: ``` -cargo test normal_tests +journalctl --user -u parsec ``` -*Note:* if you encounter a "Permission Denied" error while executing the end-to-end tests, make sure -that the group change has taken effect. You can check it by calling `groups` with no arguments. If -you do not see `parsec-clients`, please try logging the user out and in again to apply the change. - -Check the Parsec logs with: +Also reload the service with: ``` -journalclt --user -u parsec +systemctl --user kill -s HUP parsec ``` -Reload the service: +## From a parsec-clients user + +`parsec-clients` users can now use Parsec! You can test it (having logged in a `parsec-clients` +user) by installing the [`parsec-tool`](https://github.com/parallaxsecond/parsec-tool): ``` -systemctl --user kill -s HUP parsec +$ parsec-tool ping +[INFO] Pinging Parsec service... +[SUCCESS] Service wire protocol version is 1.0. ``` +*Note:* if you encounter a "Permission Denied" error while executing the end-to-end tests, make sure +that the group change has taken effect. You can check it by calling `groups` with no arguments. If +you do not see `parsec-clients`, please try logging the user out and in again to apply the change. + *Copyright 2019 Contributors to the Parsec project.* diff --git a/src/parsec_service/listeners.md b/src/parsec_service/listeners.md index 4c46e3d..4610725 100644 --- a/src/parsec_service/listeners.md +++ b/src/parsec_service/listeners.md @@ -5,6 +5,10 @@ This listener communicates with its client using a [Unix domain socket](https://en.wikipedia.org/wiki/Unix_domain_socket). -The socket path is: `/tmp/parsec/parsec.sock`. +The socket path is: `/run/parsec/parsec.sock`. + +The `socket_path` option can be used to modify the socket path, for example for testing. Clients +will expect the socket to be at the default path and hence this option should not be modified for +deployment. *Copyright 2020 Contributors to the Parsec project.*