Bianca user guide

0. PREREQUISITES

In order to access Bianca you need to be a member of an active SNIC SENS or SIMPLER research project (these are called sensNNNNN or simpNNNNN, where N represent a digit). SUPR will tell you if you are a member and the account page should list the account on the resource bianca (this can also be useful to verify your username). If you do not have a project membership, you can request membership to an existing project in SUPR or read the SENS project application page to learn how to create a project.

Additionally, you must have a personal UPPMAX user account. This is separate from your SUPR account. See the user account application page if you do not have one. 

Once you are set up for login, this should also be reflected in SUPR through one or several additional account(s) at UPPMAX for the specific project(s) you are a member of.

Also note that you need to know your UPPMAX password. If you change it, it may take up to an hour before changes are reflected in bianca.

For advice on handling sensitive personal data correctly on Bianca, see our FAQ page.

1. Set up TWO factor authentication

Follow the instructions in Setting up two factor authentication.

Please note that you need to set up two factor authentication for UPPMAX and not for SUPR! If you have multiple two factor codes registered the correct is labeled UPPMAX (as seen below highlighted in green).

2. Login

Bianca is accessible from all SUNET IP addresses, i.e. all Swedish university networks. It is generally NOT accessible from other networks. Use your university's VPN if needed.

The login procedure requires you to pass two separate authentication mechanisms (automatically connected together). The first one logs you into the general Bianca login node (which we call the jumphost). This is the step that requires two factor authentication. You will then be automatically redirected to your project's private login node, where you will get a new password prompt (unless you set up ssh-keys).

The user name you will use in the first step is your ordinary UPPMAX user name, followed by the project ID of the project you want to work on. One of the security measures on Bianca is that all projects are kept separate on their own virtual clusters, so you must tell Bianca which project's cluster you want to connect to.

Primary login (text login)

You can use any ssh-program in all normal platforms (Windows, Mac, Linux). You can have multiple log-ins active at once.

$ ssh -A <username>-<projid>@bianca.uppmax.uu.se
Ex.
$ ssh -A myname-sens2016999@bianca.uppmax.uu.se

As password you use your normal UPPMAX password directly followed by the six digits from the second factor application from step 1.

E.g. if your password is "VerySecret" and the second factor code is 123 456 you would type VerySecret123456 as the password in this step.

If the password is correct you will get a message of your projects login node status. It can be "up and running" or "down". If it is down it will automatically spin up, but this takes a few minutes. Then you will be automatically redirected to login at your project's private login node. To be able to login there you will have to give your UPPMAX password once again, but without the two factor authentication code this time. If your password is "VerySecret" you would type in VerySecret as password in this step. To skip this password in the future, you can use ssh-keys.

If the passwords have been entered correctly, you should now be connected and you will see the computer name at the start of the command line which looks something like this:

[myuser@sens2016999-bianca ~]$

This text login is limited to 50kBit/s, so if you create a lot of text output you will have to wait some time before you get your prompt back. The system supports all cut and paste mechanisms your client computer support, but of course you are not supposed to transfer any real data in or out through this mechanism — only commands and stuff like that.

Graphical login

Bianca does not support any X-forwarding, so to use graphical applications you need to have a full graphical desktop login. Bianca uses "Thinlinc" (in webaccess mode only) with XFCE as desktop environment for this. All you should need is a rather modern browser on any platform; we have tested on Chrome and Firefox.

Just browse to: https://bianca.uppmax.uu.se

The same principle with login name and password as with text logins: first step with user-project as username and password with password followed by second factor 6 digit number, and then second step to the login node for your specific project with normal username (and here you really have to type that – in text mode that is done automatically) and normal UPPMAX password (without second factor). The redirection to the correct project login node works automatically. If the login node is sleeping you will be informed what to do.

When you are logged into your graphical environment, the resizing and even fullscreen mode (in your browser) should work as expected.

Under the hidden tab in the left edge of the screen you can find a clipboard, some keys (where the keyboard versions often interfere with your local system) and the "disconnect" button. It is important to understand the difference of "disconnect session" and "end session". When you disconnect a session you will get back exactly in the same place you left the system; if you for example edit a file, your prompt will be in the same place you left it at the next login. If you use "logout" (end session) in the XFCE menus, the system will try to close all your windows and files and end the processes related to the login.

Bianca has a autodisconnect after 30 minutes of inactivity, and in the future it is possible that we implement some kind of "automatic log out from active graphical session". 

3. Transfer files to and from Bianca

For security reasons, there is no internet access on Bianca so you can't download from or upload files to the cluster directly.

In order to transfer files from Bianca you have to go through the following two steps.

First step is on Bianca.
All files must be transferred through the wharf area of Bianca. The wharf has access to one of the folders in your project folder, but nothing else outside of it. The path to this folder, once you are logged into your project's cluster, is:

/proj/<projid>/nobackup/wharf/<username>/<username>-<projid>
E.g.
/proj/sens2016999/nobackup/wharf/myuser/myuser-sens2016999

Copy the files you want to transfer to your wharf directory.

Second step is from a computer outside of Bianca. 
Remeber that sensitive data must be handled correctly also outside of Bianca!
To reach this catalog from the "outside" you need to use sftp.

To avoid subtle error with the transfers -- please make sure you have write permissions for "owner" on the source files and directories.

Using standard sftp client

$ sftp -q <username>-<projid>@bianca-sftp.uppmax.uu.se
Ex.
$ sftp -q myuser-sens2016999@bianca-sftp.uppmax.uu.se

Notice the different host name!

The -q flag is to be quiet (not showing the banner intended to help someone trying to ssh to the host), if your client does not support it, you can just skip it.

As password you use your normal UPPMAX password directly followed by
the six digits from the second factor application from step 1.

Ex. if your password is "VerySecret" and the second factor code is 123 456 you would type VerySecret123456 as the password in this step.

Once connected you will have to type the sftp commands to upload/download files. Have a look at the Basic SFTP commands guide to get started with it.

Please note that in the wharf you only have access to upload your files to the directory that is named:

<username>-<projid>
e.g.
myuser-sens2016999

so you will want to cd to that directory the first thing you do.

sftp> cd myuser-sens2016999

Alternatively, you can specify this at the end of the sftp command, so that you will always end up in the correct folder directly.

$ sftp -q <username>-<projid>@bianca-sftp.uppmax.uu.se:<username>-<projid>
E.g.
$ sftp -q myuser-sens2016999@bianca-sftp.uppmax.uu.se:myuser-sens2016999

sftp supports a recursive flag (put -r), but it seems to be very sensitive to combinations of different sftp servers and clients, so be warned... a bit further down you can see a rough solution for bulk transfers.

Some other sftp client

Please notice that sftp is NOT the same as scp. So be sure to really use a sftp client -- not just a scp client.

Also be aware that many sftp clients use reconnects (with a cached version of your password). This will not work for Bianca, because of the second factor! And some try to use multiple connections with the same password, which will fail.

So for example with lftp, you need to "set net:connection_limit 1". lftp may also defer the actual connection until it's really required unless you end your connect URL with a path.

An example command line for lftp would be

lftp sftp://<username>-<projname>@bianca-sftp.uppmax.uu.se/<username>-<projname>/

Mounting the sftp-server with sshfs

This is only possible on your own system. sshfs allows you to mount the wharf on your own machine. You will be able to copy and work on the data using your own local tools such as cp or vim. Remember that you are neither logged in on the distant server, nor is the data physically on your local disk (until you have copied it).

UPPMAX doesn't have sshfs client package installed for security reasons. sshfs is available on most Linux distributions: install the package sshfs on Ubuntu, fuse-sshfs on Fedora, RHEL7/CentOS7 (enable EPEL repository) and RHEL8 (enable codeready-builder repository) / CentOS8 (enable powertools repository).

It also exists on Windows and Mac OS X. Mac OS users have reported difficulties to set the permissions properly, this seems to be resolved with the option defer_permissions.

When you have sshfs installed, you can mount the wharf. With a Linux client (as normal user):

mkdir ~/wharf_mnt

sshfs <username>-<projname>@bianca-sftp.uppmax.uu.se:<username>-<projname> ~/wharf_mnt

Or on a Mac:

sshfs -o defer_permissions <username>-<projname>@bianca-sftp.uppmax.uu.se:<username>-<projname> ~/wharf_mnt

After that you can use wharf_mnt exactly as a local directory. For example with rsync.

To unmount it do:

fusermount -u ~/wharf_mnt

Bulk recursive transfer with only standard sftp client

It seems to be rather common with directory structures with symbolic links inside the directories that you should transfer. This is a very simple solution to copy everything in a specific folder (and follow symbolic links) to the wharf.

==============
~/sftp-upload.sh
==============
#!/bin/bash
#sftp-upload.sh
find $* -type d | awk '{print "mkdir","\""$0"\""}' 
find $* -type f | awk '{print "put","\""$0"\"","\""$0"\"" }' 
find $* -type l | awk '{print "put","\""$0"\"","\""$0"\"" }' 
-----------

With this script you can do:

cd /home/myuser/glob/testing/nobackup/somedata
~/sftp-upload.sh *|sftp -oBatchMode=no -b- <username>-<projid>@bianca-sftp.uppmax.uu.se:<username>-<projid>

The special "-b" makes the script stop on error.

Transit Server

You can log in to the Transit server at transit.uppmax.uu.se in the usual way (with ssh). 

The Transit server mounts your UPPMAX home directory and provides a utility that will mount a Bianca wharf as a directory. You can do this with the command

mount_wharf PROJECT [path]

If you do not provide a path, the wharf will be mounted as a directory named PROJECT in your home directory.

You can then use rsync or curl or whichever method you like to put data on your wharf.  

4. Accounts

Note that the machine you arrive at when logged in is only a so called login node, where you can do various smaller tasks, like submitting Slurm jobs and examing their result files. For larger tasks you may find that you must use our batch system to continue your tasks on other machines within the cluster.