COSMOS Portal User Guide

The ​COSMOS Portal is a web application for managing your testbed account, making reservations, and monitoring testbed resources. It is the primary interface for all COSMOS and ORBIT testbed users, from first-time registration through day-to-day experiment management. This guide covers the features available to regular users.

The portal is accessible at ​https://www.cosmos-lab.org/portal

---

Getting Started

Creating an Account

Before you can use any COSMOS or ORBIT testbed resources, you need an account. Your account is associated with an organization (research group) and must be approved by your group's PI (Principal Investigator).

1. Go to ​Register User
2. Fill in your details:
   • Username — 3-16 characters, must start with a letter. Only lowercase letters, digits, hyphens, and underscores are allowed. This becomes your login name on testbed console servers and other infrastructure machines.
   • First Name, Last Name — ASCII characters only
   • Email — must be a valid institutional email. Some organizations enforce domain restrictions (e.g., only @university.edu addresses).
   • Phone — include country code (e.g., +1 for US). The system auto-normalizes formats like (555) 123-4567.
   • Organization — select your research group from the dropdown. You can type to search/filter the list.
   • Password — minimum 8 characters and must contain uppercase, lowercase, digit, and a special character. The system also checks for common/weak passwords.
   • Mailing List — choose Full (all announcements), Digest (weekly summary), or None
3. Complete the CAPTCHA verification
4. Check your email and click the activation link within 30 minutes
5. After activation, your request is forwarded to your group PI and the global administrators for approval
6. Once approved, you receive a confirmation email and can log in immediately

If your organization is not listed, ask your PI or faculty advisor to ​register a new organization first. Organization registration follows a similar activation and approval workflow.

Logging In

1. Go to ​Portal Login
2. Enter your username and password
3. You will be taken to the Dashboard

If you forgot your password, click Forgot Password on the login page, enter your username and email, and you will receive a reset link valid for 1 hour. If you forgot your username, click Forgot Username and enter your email address — all matching usernames will be sent to you.

---

Dashboard

The Dashboard is your home page after logging in. It provides an at-a-glance summary of your account and testbed usage:

• Profile card — your name, username, email, organization, and the date your account was created
• Quick links — direct access to Edit Profile and SSH Keys pages
• Usage statistics:
  • Disk Usage — total storage used across all NFS-mounted home directories, shown in gigabytes
  • Reservations — total reservation count both all-time and for the last 4 weeks, helping you understand your testbed utilization
  • Login Time — total SSH session time and number of login sessions across all testbed consoles

Usage statistics are updated periodically (approximately every 24 hours) and may not reflect the most recent activity.

---

Account Management

Edit Profile

Click your name in the top-right corner and select Edit Profile, or use the quick link on the Dashboard.

You can update your first name, last name, email address, and phone number. Changes take effect immediately and are reflected in LDAP (the testbed's directory service), so updated email addresses will be used for all future notifications.

Change Password

On the Edit Profile page, scroll down to the Change Password section. Enter your current password, then your new password twice for confirmation. The same strength requirements as registration apply (8+ characters, mixed case, digit, special character, not a common pattern).

SSH Keys

SSH keys are essential for accessing testbed nodes during your reservations. The portal lets you manage your public keys from SSH Keys (accessible via the top-right user menu).

• Upload a key — paste your public SSH key. The portal validates the key format, type, and encoding in real-time before accepting it. Supported key types include ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256/384/521, and FIDO/U2F keys (sk-ssh-ed25519, sk-ecdsa).
• View keys — see all your uploaded keys with their type and comment/label
• Delete a key — remove individual keys you no longer need

You can upload multiple keys (e.g., one from your laptop and one from your desktop). These keys are deployed to testbed console servers (jump hosts), giving you SSH access during active reservations. On baseline node images, root SSH access is granted automatically for the duration of your reservation.

Generating SSH Keys

If you don't already have an SSH key pair, you'll need to generate one. An SSH key pair consists of a private key (kept secret on your computer) and a public key (uploaded to the portal).

On Linux or macOS:

ssh-keygen -t ed25519 -C "your_email@example.com"

This creates ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public). Copy the contents of the .pub file to paste into the portal.

On Windows: Use the built-in OpenSSH client (available in Windows 10/11) via Power Shell, or use ​PuTTYgen to generate a key pair. If using PuTTY, make sure to export the public key in OpenSSH format.

Further reading:

• ​GitHub: Generating SSH Keys — comprehensive tutorial for all platforms
• ​SSH Academy: ssh-keygen — reference for key generation options and best practices
• ​ArchWiki: SSH Keys — detailed guide covering key types, security considerations, and agent forwarding

---

SSH Access to Testbed Nodes

Once you have an approved reservation and your SSH key uploaded, you can connect to testbed nodes via SSH through the console server for your reserved domain.

Important: Your portal username is used to log in to the console servers (jump hosts) and other testbed infrastructure. On the testbed nodes themselves, you log in as root when using baseline images, or with whatever username you configure on your own custom/derivative images.

Basic SSH Connection

The general pattern for connecting to a testbed node is:

ssh -J <username>@<console>.cosmos-lab.org root@<node>

The -J flag sets up a jump host (also called a bastion host or proxy jump), routing your SSH connection through the console server to reach the internal testbed node. Your portal username authenticates you on the console; on the node itself you typically log in as root (baseline images). For example, to connect to node1-1 in sandbox SB1:

ssh -J myuser@sb1.cosmos-lab.org root@node1-1

You can also configure this permanently in your ~/.ssh/config:

Host sb1-*
    ProxyJump myuser@sb1.cosmos-lab.org

Host node1-1
    HostName node1-1
    User root
    ProxyJump myuser@sb1.cosmos-lab.org

SSH Tunneling

SSH tunnels allow you to securely access services running on testbed nodes (such as web interfaces, Jupyter notebooks, or custom dashboards) from your local machine.

Local port forwarding — forward a port from a remote testbed node to your local machine:

ssh -L 8888:localhost:8888 -J myuser@sb1.cosmos-lab.org root@node1-1

This makes port 8888 on node1-1 accessible at localhost:8888 on your machine. Useful for Jupyter notebooks, web UIs, and other services.

Dynamic SOCKS proxy — create a SOCKS proxy to route all traffic through a testbed node:

ssh -D 1080 -J myuser@sb1.cosmos-lab.org root@node1-1

Then configure your browser to use localhost:1080 as a SOCKS5 proxy.

Further reading on SSH tunneling and access:

• ​SSH Academy: SSH Tunneling — explanation of local, remote, and dynamic forwarding
• ​SSH Academy: Tunneling Examples — practical examples and use cases
• ​OpenBSD: ssh manual page — the authoritative reference for all SSH options
• ​DigitalOcean: SSH Config Tutorial — guide to setting up ~/.ssh/config for convenience

---

Scheduler

The Scheduler lets you reserve testbed resources (domains and sandboxes) for your experiments. Reservations give you exclusive access to the testbed hardware during your time slot.

Viewing the Calendar

Navigate to Scheduler in the left sidebar. The calendar displays:

• Day or Week view — toggle with the button at the top
• 12-hour or 24-hour time — toggle with the 12h/24h button; your preference is saved across sessions
• Resources listed vertically on the left, time slots (30-minute intervals) horizontally
• Date navigation with previous/next arrows, a Today button, and a date picker
• A clock bar showing your local timezone, UTC, and COSMOS Eastern Time
• Past time slots are grayed out and cannot be clicked

Reservation Colors

The scheduler uses distinct colors to help you quickly identify reservation ownership and status:

Color	Meaning
Green	Your approved reservation — confirmed and ready to use
Purple	Your pending reservation — submitted, waiting for approval
Blue	Another user's approved reservation
Yellow	Another user's pending reservation
Red	Conflict — overlapping pending reservations from different users
Dark gray	Blackout period — testbed unavailable for maintenance
Orange	Scheduled maintenance window

Creating a Reservation

1. Click on an empty (non-grayed) time slot in the calendar for the resource you want
2. In the dialog that appears, configure:
   • Start and end date/time — adjust using the date picker and time dropdown (respects your 12h/24h preference). You cannot create reservations in the past.
   • Summary (optional) — a short description of your experiment or purpose
   • Invite users (optional) — search by name or username to add participants who should have SSH access during your reservation
   • Group reservation (optional) — toggle this to grant access to all members of a selected organization
   • Recurrence (optional) — set up weekly or monthly recurring reservations with an end date
3. Click Submit

Your reservation appears immediately as pending (purple). It will be approved automatically based on the following schedule:

• Requests submitted before noon Eastern Time are pre-approved for the following day by 2:00 PM
• Other requests are approved at the start of the reserved time slot (just-in-time approval)

Each resource may have minimum and maximum reservation durations, which are displayed in the creation dialog.

Competing for a Slot

If another user has a pending reservation on a slot you want, click their reservation and select Compete for this slot. The auto-approver resolves conflicts using a fairness algorithm based on recent usage — users who have consumed fewer testbed hours in the past two weeks are given priority. To ensure fair resolution, avoid competing for slots that start in less than 2 hours.

Modifying or Canceling

Click on any of your reservations to view its details:

• Edit — change the time, date, duration, participants, or summary. Note: editing resets the reservation to pending status for re-approval.
• Cancel — remove a single reservation
• Delete Series — cancel all future occurrences of a recurring reservation series

My Reservations

Navigate to My Reservations in the sidebar for a consolidated view:

• Your usage statistics — total reservation hours over the last 28 days
• A sortable table of all upcoming and recent reservations showing resource name, time, duration, and status
• Quick cancel buttons for each active reservation

---

Testbed Status

Status pages appear in the sidebar only when you have an active or upcoming reservation (within 24 hours). This restriction ensures that experiment information is not exposed to users without current access. Global administrators can see all status pages at all times.

Testbed Status

Shows the power state of all nodes in each testbed domain as a visual grid. Select a testbed from the dropdown — only testbeds for which you have an active reservation are shown.

The grid displays nodes positioned by their physical coordinates (X/Y), grouped by type (Nodes, Servers, RF Devices, Virtual Machines). Each cell is color-coded:

• Green — powered on
• Dark — powered off
• Yellow — unreachable (network issue)
• Gray — not registered or unknown state

Hover over any cell to see the node's name, FQDN, and current state. The grid auto-refreshes every 30 seconds.

RF Matrix (SB4)

The RF Matrix page is available only when you have a reservation for the SB4 sandbox. It visualizes and controls the JFW 50PMA-012 RF attenuation matrix.

Features:

• Interactive network topology graph showing port connections and current attenuation values
• Click any connection to set its attenuation (0-63 dB)
• Toggle Wi Fi/SDR antenna mode per port
• Reset All — set all attenuations to 0 dB and switch to Wi Fi mode
• Save/Load configurations — save your matrix setup with a name for later reuse (can be public or private)
• The topology auto-refreshes every 5 seconds to reflect changes from all sources

---

Directory

The Directory section lets you browse the COSMOS/ORBIT user community.

Users

Navigate to Users in the sidebar to browse all registered users. You can:

• Filter alphabetically by clicking a letter (A-Z)
• Search by name, username, or email
• Sort by any column header (Username, Name, Email, Group, Created date)
• Results are paginated with 20 users per page

Groups

Navigate to Groups to browse all registered organizations. You can:

• Filter alphabetically or search by group name or organization name
• Click any group name to see its detail page: full member list, PI (Principal Investigator), and any sub-groups (Linux groups)

---

Navigation Reference

The portal sidebar organizes pages into sections. The following are visible to regular authenticated users:

Section	Page	Description
My Account	Dashboard	Profile summary, quick links, usage statistics
Scheduler	Scheduler	Calendar-based reservation system
	My Reservations	List and manage your upcoming reservations
Status	Testbed Status	Node power state grid (requires active reservation)
	RF Matrix (SB4)	RF attenuation matrix control (requires SB4 reservation)
Directory	Users	Browse all registered users
	Groups	Browse all organizations and their members

Additional sections appear for PI/Group Admins (group member management) and Global Admins (user/group approval, scheduler management, inventory, and more).

The top-right corner shows your name with a dropdown menu for Edit Profile, SSH Keys, and Log Out.

---

Tips and Troubleshooting

• Mobile friendly — on small screens, the sidebar collapses into a hamburger menu accessible from the top-left
• Hover for help — each sidebar link has a small info icon; hover over it to see a tooltip describing the page
• Keyboard shortcuts — press Escape to close any modal dialog
• Timezone awareness — the scheduler shows times in your local timezone by default, with UTC and COSMOS Eastern Time references in the clock bar
• Time format — use the 12h/24h toggle button on the scheduler to switch between AM/PM and 24-hour format; your preference is remembered
• Session timeout — if your session expires, the portal redirects you to the login page; your last URL is preserved so you return to the same page after logging in
• SSH connection refused — verify that your reservation is currently active (approved, not just pending) and that your public key is uploaded in the SSH Keys page
• Key not working — make sure you uploaded the public key (.pub file), not the private key. The portal validates the format on upload.
• Can't see status pages — status pages only appear when you have a current or upcoming reservation (within 24 hours)

---

External Resources

• ​COSMOS Project Homepage
• ​ORBIT Lab Homepage
• ​COSMOS Wiki
• ​OpenSSH Project — the SSH implementation used on all testbed nodes
• ​SSH Academy — tutorials and reference material for SSH, keys, and tunneling
• ​GitHub SSH Guide — beginner-friendly SSH key setup guide (applicable beyond Git Hub)