Getting Started

This is a guide for anyone who has received an invitation to join an Isambard project.

Step 1: Log into the portal

The first step is to connect to the BriCS portal. This is at the address https://portal.isambard.ac.uk.

You will see a login page that will look something like this.

Click the button marked "Sign in with federation. Click here to login".

This will take you to a page where you can choose which identity provider you want to use to log in.

There are three choices of identity provider:

• University Login (MyAccessID)
• Other Login (IdP of last resort)
• BriCS (Administrators Only)

You need to choose an option that matches the email address at which you received your invitation.

Choose the "University Login" option if your invitation was received by your University account. This will let you use your own University account to log in.

Choose the "Other Login" option if you don't have a University account, or if you received your invitation at a different email address.

The "BriCS" option is only for administrators, and should not be used.

Step 1.1: University Login (MyAccessID)

If you choose the "University Login" option, then you will be taken to a MyAccessID login page.

Start typing in the name of your University. You will hopefully see your University appear in the list of options.

Click on your University - this will take you to your normal University login page. Log in as you would normally. This will bring you back to the BriCS portal.

Email us if your University isn't listed. We will then set up an account for you using the "Other Login" option.

Checking MyAccessID support at your institution

Check here for the level of MyAccessID support at your University.

Step 1.2: Other Login (IdP of last resort)

You can only use this option if we have set up an account for your on the Identity Provider of Last Resort (IdP of last resort). This is a special identity provider that we use for people who don't have a University account, or whose University does not yet support the REFEDS Research and Scholarship category.

This is provided by AWS Identity Center. If you need this, we will create an account for you in our AWS Identity Center, and will send you login instructions. Once set up, you will be able to log in by clicking on the "Other Login" button, and then entering your email and login details at the prompt.

Things that can go wrong at Step 1

If everything worked, you move onto Step 2 (Accepting Policies). However, there are a number of things that can go wrong.

Wrong email address

You must log in using the email address at which you received your invitation. If you don't then you will seen an error screen that will be something like this.

This shows that there is no record of an account of invitation for you at the email address you used to log in. Your email address will be shown at the bottom of this error message. Please get in touch with the person who invited you and let them know that they used the wrong email address in their invitation. They have to use the email address as it is shown in this error message.

Pending invitation

Most invitations will be approved automatically. However, in a small number of cases the invitation will need to be reviewed before it can be approved. If this is the case, you will see a screen like this.

The expectation is that your invitation will be processed quickly. As the message says, if it takes longer, then either email us or contact the person who invited you and ask them to raise a support ticket.

Tip

The displayed message shows who invited you and which email address you used to log in. This is useful information to include in any support request.

Step 2: Accepting Policies

The Bristol Centre for Supercomputing (BriCS) has a number of policies that must be accepted before you can use any of its services. As soon as you log in, you will be presented with a list of policies that you need to accept to continue. You will see them in screens that look something like this.

Please click the link to open the policy in a new tab. Take time to read the policy. It is very important for compliance reasons that you read and understand, and that we have a clear record of your acceptance.

Once you have read the policy, type "accept" into the text box, and click the "Submit" button.

You will have to read and accept at least two policies, i.e. after the Data Privacy Policy you will also have to read and accept the Acceptable Use Policy.

The date and time that you accepted the policies will be recorded with your account, so you shouldn't need to accept them when you log in again. However, if there are any new policies or anything changes then you will be shown the policies and will need to accept again.

Step 3: Choosing a UNIX username

You will next be brought to a page where you initialise your user account.

Here you can choose a UNIX user name. This will be used to create the name of your account on the supercomputers. Please choose a short, unique name for you. It should only contain lower-case letters and digits, and must start with a letter. It can be between 5-20 characters long.

UNIX user names are permanent

You cannot change your UNIX user name after it has been set. Please take time to choose a name that you are happy with.

Once you have chosen, scroll down to (optionally) upload an avatar.

Once you are happy, click "Agree and proceed" to show you are happy with your choice of UNIX user name, and that you (again) accept the usage policies.

Step 4: Accepting the Invitation

Now you have logged in and completed your account, you should (finally!) see the portal. However, you will see a message, like this, saying your account isn't associated with any projects.

This is because you haven't (yet) accepted the invitation.

Find the email that contained your invitation. Note that it may have gone into your spam folder. It should look something like this.

Click on the link in the email (or copy the link and paste it into the address bar in your browser). Make sure that you use the same browser that you used to log in above (or else you will need to log in again).

You will now see a box asking if you want to accept the invitation.

Click "Accept invitation" if you want to accept and join the project.

Click "Cancel invitation" if, for any reason, and after all of the above, you decide that you don't want to use any of the centre's services, and do not want to join the project. Note, cancelling the invitation will block your account. Your data will be retained as described in the Data Privacy Policy for a period of time to satisfy cybersecurity and compliance requirements, after which it will be deleted.

Accidentally cancelled invitation

Get in touch with the person who invited you and ask them to send the invitation again if you accidentally clicked "Cancel invitation".

Step 5: Generating your SSH key pair

The next step is to make sure you have an SSH key pair. This is used to authenticate you when you try to log into any of the centre's supercomputers using SSH.

Supported SSH key types

We only support modern SSH keys (i.e. RSA keys of 3072 bits or more, or Ed25519, or any other modern, post-2014 key type). We do not support DSA keys, or RSA keys of less than 3072 bits. Any key generated using a modern version of ssh-keygen should be fine, e.g. the private key must contain -----BEGIN OPENSSH PRIVATE KEY-----

If you already have a key pair then feel free to use it. But if you don't have an SSH key then you can generate one using ssh-keygen. Instructions on how to do this can be found by at, for example, GitHub's documentation on generating an SSH key.

Setting up an ssh-agent (as described in that previous link) is not a requirement, but we recommend it.

Step 6: Logging into the BriCS Supercomputers with SSH and Clifton

Account Creation

You will not be able to connect to the BriCS facilities using SSH until your account has been created. Account creation can take up to one business day after setting your UNIX username.

To connect to one of the BriCS facilities using SSH you will need to use signed SSH certificates. We provide a command line tool called Clifton for obtaining SSH certificates and configuring your SSH client to use these. The certificates are valid for 12 hours.

First check the latest release of Clifton for the name of the executable for your platform, e.g. to download the executable for Apple Silicon (Arm) Macs (clifton-macos-aarch64) from the command line using curl:

curl -L https://github.com/isambard-sc/clifton/releases/latest/download/clifton-macos-aarch64 -o clifton

You can also download the executable for the latest release of Clifton through your web browser.

Make Clifton executable

On Linux and macOS, you will have to use chmod u+x clifton to make clifton executable.

Allowing Clifton to run on macOS

If you download the Clifton through your web browser, you may be presented with a macOS warning dialog when trying to run the executable, e.g.

"clifton-macos-aarch64" can't be opened because Apple cannot check it for malicious software.

If this occurs you will have to go into "System Settings > Privacy & Security" and allow use of the clifton executable (see Open a Mac app from an unidentified developer from the macOS documentation). Note that you will need to have admin privileges to change the settings in "Privacy & Security".

To use Clifton to obtain an SSH certificate:

./clifton auth

Specify an SSH key for Clifton to use

By default Clifton will look for existing SSH keys in standard locations (e.g. ~/.ssh/id_ed25519). If the your SSH key is in a non-standard location, you can tell Clifton which key to use to create the certificate by using the --identity option, e.g.

./clifton auth --identity /path/to/ssh_key

The auth command will open your browser and direct you to the portal, where you can authorise access to Clifton. Alternatively, you can scan the QR code on your mobile. On successful authentication you will see something like the following:

Successfully authenticated as YOUR_EMAIL_ADDRESS (YOUR_SHORT_NAME) and downloaded SSH certificate for projects:
 - PROJECT_NAME

Certificate file written to ~/.ssh/id_ed25519-cert.pub
Certificate valid for 11 hours and 59 minutes.
You may now want to run `clifton ssh-config write` to configure your SSH config aliases.

Using the ssh-config write command, Clifton will write a ssh config file ~/.ssh/config_clifton and Include it in your main ssh config ~/.ssh/config:

./clifton ssh-config write

You will now be able to login using your project-specific account into a BriCS facility that the project is authorised to access. Currently, FACILITY would be aip1 or 3 for Isambard-AI and Isambard 3 respectively.

ssh PROJECT_NAME.FACILITY.isambard

SSH Certificates are only valid for 12 Hours

Your signed SSH certificates are only valid for 12 hours. After 12 hours, you will need to rerun ./clifton auth

Step 7: Getting support (Helpdesk)

The best way to get help is to use our helpdesk.

You can log into this by going to either https://helpdesk.isambard.ac.uk or https://support.isambard.ac.uk.

When you go there you will see a login screen that will look something like this.

Click "Click here to login" to log in. This may take you back to the federated login page as before. If that happens, log in using your chosen identity provider (e.g. University Login or Other Login).

Once you have logged in, you will see the helpdesk.

This will show all of the tickets you have submitted, plus their status.

At the moment, you haven't submitted any tickets.

To submit a ticket, scroll down the page to see these buttons.

The left button, with your initials, is for updating your profile or for logging out. The right button (the "+" sign) is for submitting a ticket.

Click on this to be brought to the ticket submission page.

Fill in the title of your ticket, and then put in the details in the "TEXT" section. You can also attach files if you need to, e.g. screenshots. Try to give as much information as you can, e.g. what project you are working on, what you are trying to do, and which supercomputer you were using.

When you are ready, click the "Create" button to create and submit the ticket.

Or, if you want to cancel, click "Cancel & Go Back" to cancel the submission and go back to the helpdesk.

Step 8 (PIs only): Manage members of your project

If you are a Principal Investigator (PI) for a BriCS project, you can manage (add and remove) in your project in the portal.

Not a PI?

A PI should already have invited you to join a project and this should be visible to you in the portal. If you would like to be added to or removed from a project, please contact that project's PI directly.

Inviting someone to your project

There are three roles you can have on a project:

• Researcher
• Co-investigator
• Principal Investigator

The Principal Investigator (PI) is a special role that should be held only by the person (or people) who are legally responsible for the project.

The PI will have to accept specific Terms and Conditions (provided separately) that relate to their use of the project and their obligations to the Bristol Centre for Supercomputing and its funders.

Because of this, ONLY the PI can invite people onto their project.

In doing so, the PI confirms that they have conducted the required due diligence on the person they are inviting, and that they are happy to take responsibility for the actions of the person they invite.

To invite someone to your project, go to the project page (click the "Projects" link in the left menu).

Click on the project that you want to invite someone to. This will take you to that project's management page.

Click the "Team" drop-down in the menu, then "Invitations". This will take you to the invitations page.

Click the "Invite user" button to open the invitation dialog.

Type in the email address of the person you want to invite. Then choose the role you want to give them.

Inviting another PI

Only invite another Principal Investigator if you are happy to share responsibility for the project with them, and you are sure that they are legally responsible for the project and will comply with the terms and conditions.

Which e-mail address to use?

Make sure you use the correct email address for the person you are inviting. Prefer their standard University email if they have one. Please raise a ticket in the helpdesk if you want to invite someone who does not have a University email address. We will discuss with you if this is possible and how to proceed.

Click "Continue" to move to the next page...

Here you can add a message that will be appended to the invitation. Make sure to write something that will explain to the person you are inviting what they need to do next (e.g. point them to this guide).

Once ready, click the "Send invitation" button to send the invitation. This will be emailed to the person you are inviting.

You will be taken back to the invitations page. Here you will see all of the invitations you have sent, and their status.

You can cancel an invitation by clicking the "Cancel" button next to it, or resend the email by clicking the "Resend" button.

Invitation expiry

An invitation is only valid for 7 days. You can see the date it expires under the "EXPIRES AT" column.

Removing someone from your project

If you need to remove someone from your project, go to the project page and click on the "Team" drop-down in the menu, then "Users".

Click "Edit" if you want to edit the user (e.g. to change their role, or to set a date at which they will be automatically removed).

Click "Remove" if you want to remove the user from the project.

This will immediately prevent the user from creating new logins or new connections to your project. However, they may still have existing connections that will remain active until they expire.

Please raise a ticket in the helpdesk if you want to urgently remove someone from your project. We will block that user from all services immediately.

Project membership is required to access the portal

People can only log into the portal if they are invited to or active in at least one project. If you remove someone from all of their projects, then they will not be able to log in.

Data retention for after removing a user

The data associated with a user will be retained as described in the Data Privacy Policy for a period of time to satisfy cybersecurity and compliance requirements, after which it will be deleted.

The PI is responsible for managing data in project storage

Project data is managed and is the responsibility of the Principal Investigator. Removing a user from a project will NOT remove their data from the shared project storage.

What's next?

Now that you have logged in and accepted the policies, you can start using the services provided by the Bristol Centre for Supercomputing.

What to do next depends on what services you have access to and plan to use. Please explore the rest of the documentation to learn more.

Raise a ticket in the helpdesk if you have any questions or need help.