# Escudo NAS Service

This document describes the Escudo NAS storage service: what it offers, how
accounts are managed, and how to connect to it.

## Overview

The Escudo NAS provides personal network storage for IAC users, intended for
backups and for keeping data that does not need to live on a high-performance
filesystem. Access is via `rsync` and `sshfs` over SSH, using the `opkssh`
two-factor authentication mechanism.

## What you get

- **Quota:** each user gets **2 TB** of personal space.
- **Access protocols:** `rsync` and `sshfs` over SSH (no SMB/NFS exports,
  no web interface).
- **No automatic deletion of files:** there is no quota-based or age-based
  purge. Files remain in place for as long as the account exists.
- **Resilience:** the NAS uses a RAID-5 equivalent layout (Synology Hybrid
  RAID, SHR). Your data survives the failure of any single disk in the
  array. This is **not a substitute for your own backups** of critical data,
  but it does mean that a single disk failure on the NAS will not cause
  data loss.

## Account allocation policy

- Accounts are **primarily reserved for those users with no access to a
  project's NAS**.
- We have capacity for **about 60 accounts**. Once that limit is reached, new
  accounts will be granted as existing ones are freed up.
- Depending on availability, we will reach out to offer accounts to users we
  think could benefit from the service. If you would like an account, you are
  also welcome to register your interest by writing to **sinfin@iac.es**. 
- Once your account is created, it will remain valid for as long as you hold a
  contract with the IAC, subject to the periodic reviews described below.

## Periodic reviews

From time to time we review the NAS accounts to make sure resources are
being put to good use:

1. **IAC contract check.** The NAS account is tied to your IAC contract. If you
   no longer have an active contract with the IAC, your NAS account **and all of
   its files** will be deleted (regardless of whether you keep an -ext account).

2. **Continued use check.** Occasionally, when demand for the service is high
   (i.e. when other users are waiting for an account), we will contact you by
   email to confirm that you still want to keep yours.
   - If we do not hear back from you within **one month**, the account will be
     **deactivated** (you will no longer be able to log in, but the files will
     still be there).
   - If we still do not hear back within **one further month** after
     deactivation, the account and all of its files will be **deleted**.

If at any point you want to give up the account voluntarily, just let us
know and we will remove it.

## Connecting to the NAS

Access to the NAS uses a two-factor authentication mechanism based on
`opkssh`. (This is the same mechanism used to connect to LaPalma, so if you
already use LaPalma you do **not** need to install or configure anything
new. See
[https://vesta.ll.iac.es/SIE/docs/supercomputing/lapalma/connect.html#connecting-to-lapalma](https://vesta.ll.iac.es/SIE/docs/supercomputing/lapalma/connect.html#connecting-to-lapalma))

If this is the first time you use `opkssh`, follow the
[opkssh setup instructions](https://vesta.ll.iac.es/SIE/docs/supercomputing/lapalma/connect.html#two-factor-authentication-setup)
from the LaPalma documentation. The same client configuration works for
the NAS.

Once `opkssh` is configured, log in to the identity provider to obtain a
fresh certificate:

```
opkssh login
```

A browser window will open asking for your credentials. Once authentication
succeeds, your SSH certificate (`~/.ssh/id_ecdsa-cert.pub`) is generated and you
can connect to the NAS. The hostname for the service is `escudo`, and your
account name on the NAS is the same as your IAC user name.

### Example: obtaining the SSH key

```
[mymachine]$ opkssh login
INFO[0000] listening on http://127.0.0.1:3000/
INFO[0000] Opening browser to http://localhost:3000/login
# Authenticate in the browser window that opens
Writing opk ssh public key to /home/user/.ssh/id_ecdsa-cert.pub and
corresponding secret key to /home/user/.ssh/id_ecdsa
[...]
```

Note that interactive `ssh` logins to the NAS are not allowed: the only
supported ways to use it are `rsync` and `sshfs`, as described below.

> **Note on certificate lifetime.** As on LaPalma, the certificate generated by
> `opkssh login` has a limited lifetime of 24 hours. When it expires you just
> need to run `opkssh login` again before reconnecting. There is no need to
> repeat the initial setup.

### Copying files with `rsync`

To mirror a local directory to your NAS account (here, user `user`
mirroring the local directory `user/` to the home directory on the NAS):

```
rsync -av --delete user/ user@escudo:
```

> **First-time use.** On the very first connection, SSH will ask you to
> accept the host key of the NAS. Answer `yes` to continue. The key is
> then stored in your `~/.ssh/known_hosts` and you will not be asked
> again.

The `--delete` flag makes the destination an exact mirror of the source
(files removed locally will be removed on the NAS too). Drop it if you
want an append-only copy.

### Mounting with `sshfs`

To mount your NAS home directory locally as if it were a regular folder:

```
mkdir -p escudo
sshfs user@escudo:/homes/user escudo/
```

You can then read and write files under `escudo/` with any local tool.
To unmount:

```
fusermount -u escudo
```

(on macOS use `umount escudo` instead).

## Support

For account requests, renewals, or any problem with the service, please
contact the SIE team.

Announcements about service availability, scheduled maintenance, incidents
and similar topics are posted in the **#computing/storage** channel on
IAC-Zulip.