Skip to content

Update instraction after installation path changes #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 2, 2020
Merged

Update instraction after installation path changes #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4be6431
Update instraction after installation path changes
hug-dev Sep 24, 2020
5653474
Update the build-run instructions
hug-dev Sep 28, 2020
2b798a2
Regroup commands together for folder creation
hug-dev Sep 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 18 additions & 20 deletions src/parsec_service/build_run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cheers 😅

```````

## Killing Parsec
Expand Down
82 changes: 55 additions & 27 deletions src/parsec_service/install_parsec_linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -34,32 +54,36 @@ 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
```

Depending on which features of Parsec the `parsec` user is going to use, it might need to be given
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.
Expand All @@ -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.*
6 changes: 5 additions & 1 deletion src/parsec_service/listeners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.*