| 8 | | ---- |
| 9 | | |
| 10 | | == Getting Started == #GettingStarted |
| 11 | | |
| 12 | | === Creating an Account === #CreateAccount |
| 13 | | |
| 14 | | 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). |
| 15 | | |
| 16 | | 1. Go to [https://www.cosmos-lab.org/register_usr Register User] |
| 17 | | 2. Fill in your details: |
| 18 | | * '''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. |
| 19 | | * '''First Name, Last Name''' -- ASCII characters only |
| 20 | | * '''Email''' -- must be a valid institutional email. Some organizations enforce domain restrictions (e.g., only @university.edu addresses). |
| 21 | | * '''Phone''' -- include country code (e.g., +1 for US). The system auto-normalizes formats like (555) 123-4567. |
| 22 | | * '''Organization''' -- select your research group from the dropdown. You can type to search/filter the list. |
| 23 | | * '''Password''' -- minimum 8 characters and must contain uppercase, lowercase, digit, and a special character. The system also checks for common/weak passwords. |
| 24 | | * '''Mailing List''' -- choose Full (all announcements), Digest (weekly summary), or None |
| 25 | | 3. Complete the CAPTCHA verification |
| 26 | | 4. Check your email and click the activation link within 30 minutes |
| 27 | | 5. After activation, your request is forwarded to your group PI and the global administrators for approval |
| 28 | | 6. Once approved, you receive a confirmation email and can log in immediately |
| 29 | | |
| 30 | | [[Image(portal-register.png, width=40%)]] |
| 31 | | |
| 32 | | If your organization is not listed, ask your PI or faculty advisor to [https://www.cosmos-lab.org/register_org register a new organization] first. Organization registration follows a similar activation and approval workflow. |
| 33 | | |
| 34 | | === Logging In === #Login |
| 35 | | |
| 36 | | 1. Go to [https://www.cosmos-lab.org/portal/login Portal Login] |
| 37 | | 2. Enter your username and password |
| 38 | | 3. You will be taken to the Dashboard |
| 39 | | |
| 40 | | [[Image(portal-login.png, width=30%)]] |
| 41 | | |
| 42 | | 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. |
| | 8 | Every authenticated user sees a left-hand sidebar organized into sections. The sections and pages available to you depend on your role (regular user, PI/Group Admin, or Global Admin). This guide covers the features visible to all regular authenticated users. The sidebar collapses into a hamburger menu on mobile devices for a fully responsive experience. |
| 59 | | [[Image(portal-dashboard.png, width=50%)]] |
| | 20 | === [wiki:UserGuide/Portal/Dashboard Dashboard] === |
| | 21 | |
| | 22 | Your home page after logging in. The Dashboard provides an at-a-glance summary of your profile, disk usage, reservation history, and login activity. It also features quick links to frequently used pages and a Community Forum link that opens a discussion popup where you can interact with other testbed users. |
| | 23 | |
| | 24 | === [wiki:UserGuide/Portal/Account Account Management] === |
| | 25 | |
| | 26 | Manage your profile information, change your password, and upload SSH public keys. SSH keys are essential for connecting to testbed nodes during your experiments — the portal validates key format and type in real time and supports modern key types including Ed25519, ECDSA, and FIDO/U2F hardware keys. This section includes step-by-step instructions for generating keys on Linux, macOS, and Windows. |
| | 27 | |
| | 28 | === [wiki:UserGuide/Portal/SSH SSH Access] === |
| | 29 | |
| | 30 | Once you have a reservation and SSH keys configured, you need to connect to testbed nodes. This section explains the SSH connection model: you first connect to a console server (jump host) using your portal username, then hop to individual testbed nodes as root. It covers ProxyJump configuration, SSH tunneling for web services and Jupyter notebooks, SOCKS proxies, and how to set up your `~/.ssh/config` for convenient access. |
| | 31 | |
| | 32 | === [wiki:UserGuide/Portal/Scheduler Scheduler] === |
| | 33 | |
| | 34 | The Scheduler is a calendar-based reservation system that gives you exclusive access to testbed domains and sandboxes during your time slot. This section explains how to navigate the calendar, create single and recurring reservations, invite collaborators, compete for contested time slots, and understand the automatic approval algorithm. It also documents the color coding system and the My Reservations management page. |
| | 35 | |
| | 36 | === [wiki:UserGuide/Portal/Status Testbed Status] === |
| | 37 | |
| | 38 | During active reservations, Status pages appear in the sidebar showing real-time information about the testbed domain you have reserved. The primary status page displays a visual grid of all nodes with color-coded power states (on, off, unreachable). For SB4 reservations, an RF Matrix control page lets you interactively adjust RF attenuation values between nodes. |
| | 39 | |
| | 40 | === [wiki:UserGuide/Portal/DiskImages Disk Images] === |
| | 41 | |
| | 42 | The Disk Images page lets you browse, search, and manage testbed disk images. You can view your own images, publicly available images shared by other users, and (for admins) the complete image library. Each image shows its name, owner, size, creation date, and a description. You can also manage image visibility (public/private) and delete images you own. |
| | 43 | |
| | 44 | === [wiki:UserGuide/Portal/Forum Community Forum] === |
| | 45 | |
| | 46 | The COSMOS Community Forum is an integrated discussion platform where testbed users can ask questions, share experiment results, discuss best practices, and get help from the community and testbed administrators. The forum opens in a popup window so you can keep it alongside the portal while working. It uses single sign-on — if you are logged into the portal, you are automatically logged into the forum. |
| | 47 | |
| | 48 | === [wiki:UserGuide/Portal/Directory Directory] === |
| | 49 | |
| | 50 | The Directory section lets you browse the COSMOS/ORBIT user community. You can search and filter the complete list of registered users by name, username, or email, and browse all registered organizations with their members and PIs. |
| 67 | | Click your name in the top-right corner and select '''Edit Profile''', or use the quick link on the Dashboard. |
| 68 | | |
| 69 | | 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. |
| 70 | | |
| 71 | | [[Image(portal-profile.png, width=40%)]] |
| 72 | | |
| 73 | | === Change Password === #Password |
| 74 | | |
| 75 | | 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). |
| 76 | | |
| 77 | | === SSH Keys === #SSHKeys |
| 78 | | |
| 79 | | 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). |
| 80 | | |
| 81 | | * '''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). |
| 82 | | * '''View keys''' -- see all your uploaded keys with their type and comment/label |
| 83 | | * '''Delete a key''' -- remove individual keys you no longer need |
| 84 | | |
| 85 | | 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. |
| 86 | | |
| 87 | | [[Image(portal-ssh-keys.png, width=40%)]] |
| 88 | | |
| 89 | | ==== Generating SSH Keys ==== |
| 90 | | |
| 91 | | 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). |
| 92 | | |
| 93 | | '''On Linux or macOS:''' |
| 94 | | {{{ |
| 95 | | ssh-keygen -t ed25519 -C "your_email@example.com" |
| 96 | | }}} |
| 97 | | This creates `~/.ssh/id_ed25519` (private) and `~/.ssh/id_ed25519.pub` (public). Copy the contents of the `.pub` file to paste into the portal. |
| 98 | | |
| 99 | | '''On Windows:''' |
| 100 | | Use the built-in OpenSSH client (available in Windows 10/11) via PowerShell, or use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTYgen] to generate a key pair. If using PuTTY, make sure to export the public key in OpenSSH format. |
| 101 | | |
| 102 | | '''Further reading:''' |
| 103 | | * [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent GitHub: Generating SSH Keys] -- comprehensive tutorial for all platforms |
| 104 | | * [https://www.ssh.com/academy/ssh/keygen SSH Academy: ssh-keygen] -- reference for key generation options and best practices |
| 105 | | * [https://wiki.archlinux.org/title/SSH_keys ArchWiki: SSH Keys] -- detailed guide covering key types, security considerations, and agent forwarding |
| | 67 | The top-right corner of the portal shows your name with a dropdown menu providing quick access to '''Edit Profile''', '''SSH Keys''', and '''Log Out'''. |
| 111 | | 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. |
| 112 | | |
| 113 | | '''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. |
| 114 | | |
| 115 | | === Basic SSH Connection === |
| 116 | | |
| 117 | | The general pattern for connecting to a testbed node is: |
| 118 | | {{{ |
| 119 | | ssh -J <username>@<console>.cosmos-lab.org root@<node> |
| 120 | | }}} |
| 121 | | |
| 122 | | 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: |
| 123 | | {{{ |
| 124 | | ssh -J myuser@sb1.cosmos-lab.org root@node1-1 |
| 125 | | }}} |
| 126 | | |
| 127 | | You can also configure this permanently in your `~/.ssh/config`: |
| 128 | | {{{ |
| 129 | | Host sb1-* |
| 130 | | ProxyJump myuser@sb1.cosmos-lab.org |
| 131 | | |
| 132 | | Host node1-1 |
| 133 | | HostName node1-1 |
| 134 | | User root |
| 135 | | ProxyJump myuser@sb1.cosmos-lab.org |
| 136 | | }}} |
| 137 | | |
| 138 | | === SSH Tunneling === #SSHTunnel |
| 139 | | |
| 140 | | 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. |
| 141 | | |
| 142 | | '''Local port forwarding''' -- forward a port from a remote testbed node to your local machine: |
| 143 | | {{{ |
| 144 | | ssh -L 8888:localhost:8888 -J myuser@sb1.cosmos-lab.org root@node1-1 |
| 145 | | }}} |
| 146 | | This makes port 8888 on node1-1 accessible at `localhost:8888` on your machine. Useful for Jupyter notebooks, web UIs, and other services. |
| 147 | | |
| 148 | | '''Dynamic SOCKS proxy''' -- create a SOCKS proxy to route all traffic through a testbed node: |
| 149 | | {{{ |
| 150 | | ssh -D 1080 -J myuser@sb1.cosmos-lab.org root@node1-1 |
| 151 | | }}} |
| 152 | | Then configure your browser to use `localhost:1080` as a SOCKS5 proxy. |
| 153 | | |
| 154 | | '''Further reading on SSH tunneling and access:''' |
| 155 | | * [https://www.ssh.com/academy/ssh/tunneling SSH Academy: SSH Tunneling] -- explanation of local, remote, and dynamic forwarding |
| 156 | | * [https://www.ssh.com/academy/ssh/tunneling-example SSH Academy: Tunneling Examples] -- practical examples and use cases |
| 157 | | * [https://man.openbsd.org/ssh OpenBSD: ssh manual page] -- the authoritative reference for all SSH options |
| 158 | | * [https://www.digitalocean.com/community/tutorials/how-to-configure-custom-connection-options-for-your-ssh-client DigitalOcean: SSH Config Tutorial] -- guide to setting up `~/.ssh/config` for convenience |
| | 73 | * '''Mobile friendly''' — on small screens, the sidebar collapses into a hamburger menu accessible from the top-left corner. |
| | 74 | * '''Hover for help''' — each sidebar link has a small info icon; hover over it to see a tooltip describing the page. |
| | 75 | * '''Keyboard shortcuts''' — press Escape to close any modal dialog. |
| | 76 | * '''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. |
| | 77 | * '''Can't log in''' — use the Forgot Password or Forgot Username links on the login page. If your account is still pending approval, contact your group PI. |
| | 78 | * '''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. See the [wiki:UserGuide/Portal/SSH SSH Access] guide for detailed troubleshooting. |
| | 79 | * '''Can't see status pages''' — Status pages only appear when you have a current or upcoming reservation. Global administrators see all status pages. |
| 162 | | == Scheduler == #Scheduler |
| 163 | | |
| 164 | | 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. |
| 165 | | |
| 166 | | === Viewing the Calendar === #Calendar |
| 167 | | |
| 168 | | Navigate to '''Scheduler''' in the left sidebar. The calendar displays: |
| 169 | | * '''Day''' or '''Week''' view -- toggle with the button at the top |
| 170 | | * '''12-hour or 24-hour time''' -- toggle with the 12h/24h button; your preference is saved across sessions |
| 171 | | * Resources listed vertically on the left, time slots (30-minute intervals) horizontally |
| 172 | | * Date navigation with previous/next arrows, a Today button, and a date picker |
| 173 | | * A clock bar showing your local timezone, UTC, and COSMOS Eastern Time |
| 174 | | * Past time slots are grayed out and cannot be clicked |
| 175 | | |
| 176 | | [[Image(portal-scheduler.png, width=50%)]] |
| 177 | | |
| 178 | | === Reservation Colors === #Colors |
| 179 | | |
| 180 | | The scheduler uses distinct colors to help you quickly identify reservation ownership and status: |
| 181 | | |
| 182 | | ||= Color =||= Meaning =|| |
| 183 | | || '''Green''' || Your approved reservation — confirmed and ready to use || |
| 184 | | || '''Purple''' || Your pending reservation — submitted, waiting for approval || |
| 185 | | || '''Blue''' || Another user's approved reservation || |
| 186 | | || '''Yellow''' || Another user's pending reservation || |
| 187 | | || '''Red''' || Conflict — overlapping pending reservations from different users || |
| 188 | | || '''Dark gray''' || Blackout period — testbed unavailable for maintenance || |
| 189 | | || '''Orange''' || Scheduled maintenance window || |
| 190 | | |
| 191 | | === Creating a Reservation === #CreateReservation |
| 192 | | |
| 193 | | 1. Click on an empty (non-grayed) time slot in the calendar for the resource you want |
| 194 | | 2. In the dialog that appears, configure: |
| 195 | | * '''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. |
| 196 | | * '''Summary''' (optional) -- a short description of your experiment or purpose |
| 197 | | * '''Invite users''' (optional) -- search by name or username to add participants who should have SSH access during your reservation |
| 198 | | * '''Group reservation''' (optional) -- toggle this to grant access to all members of a selected organization |
| 199 | | * '''Recurrence''' (optional) -- set up weekly or monthly recurring reservations with an end date |
| 200 | | 3. Click '''Submit''' |
| 201 | | |
| 202 | | Your reservation appears immediately as pending (purple). It will be approved automatically based on the following schedule: |
| 203 | | * Requests submitted before noon Eastern Time are pre-approved for the following day by 2:00 PM |
| 204 | | * Other requests are approved at the start of the reserved time slot (just-in-time approval) |
| 205 | | |
| 206 | | Each resource may have minimum and maximum reservation durations, which are displayed in the creation dialog. |
| 207 | | |
| 208 | | === Competing for a Slot === #Compete |
| 209 | | |
| 210 | | 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. |
| 211 | | |
| 212 | | === Modifying or Canceling === #ModifyCancel |
| 213 | | |
| 214 | | Click on any of your reservations to view its details: |
| 215 | | * '''Edit''' -- change the time, date, duration, participants, or summary. Note: editing resets the reservation to pending status for re-approval. |
| 216 | | * '''Cancel''' -- remove a single reservation |
| 217 | | * '''Delete Series''' -- cancel all future occurrences of a recurring reservation series |
| 218 | | |
| 219 | | === My Reservations === #MyReservations |
| 220 | | |
| 221 | | Navigate to '''My Reservations''' in the sidebar for a consolidated view: |
| 222 | | * Your usage statistics -- total reservation hours over the last 28 days |
| 223 | | * A sortable table of all upcoming and recent reservations showing resource name, time, duration, and status |
| 224 | | * Quick cancel buttons for each active reservation |
| 225 | | |
| 226 | | [[Image(portal-my-reservations.png, width=50%)]] |
| 227 | | |
| 228 | | ---- |
| 229 | | |
| 230 | | == Testbed Status == #Status |
| 231 | | |
| 232 | | 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. |
| 233 | | |
| 234 | | === Testbed Status === #TestbedStatus |
| 235 | | |
| 236 | | 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. |
| 237 | | |
| 238 | | 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: |
| 239 | | * '''Green''' -- powered on |
| 240 | | * '''Dark''' -- powered off |
| 241 | | * '''Yellow''' -- unreachable (network issue) |
| 242 | | * '''Gray''' -- not registered or unknown state |
| 243 | | |
| 244 | | Hover over any cell to see the node's name, FQDN, and current state. The grid auto-refreshes every 30 seconds. |
| 245 | | |
| 246 | | === RF Matrix (SB4) === #RFMatrix |
| 247 | | |
| 248 | | 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. |
| 249 | | |
| 250 | | Features: |
| 251 | | * Interactive network topology graph showing port connections and current attenuation values |
| 252 | | * Click any connection to set its attenuation (0-63 dB) |
| 253 | | * Toggle WiFi/SDR antenna mode per port |
| 254 | | * '''Reset All''' -- set all attenuations to 0 dB and switch to WiFi mode |
| 255 | | * '''Save/Load configurations''' -- save your matrix setup with a name for later reuse (can be public or private) |
| 256 | | * The topology auto-refreshes every 5 seconds to reflect changes from all sources |
| 257 | | |
| 258 | | ---- |
| 259 | | |
| 260 | | == Directory == #Directory |
| 261 | | |
| 262 | | The Directory section lets you browse the COSMOS/ORBIT user community. |
| 263 | | |
| 264 | | === Users === #Users |
| 265 | | |
| 266 | | Navigate to '''Users''' in the sidebar to browse all registered users. You can: |
| 267 | | * Filter alphabetically by clicking a letter (A-Z) |
| 268 | | * Search by name, username, or email |
| 269 | | * Sort by any column header (Username, Name, Email, Group, Created date) |
| 270 | | * Results are paginated with 20 users per page |
| 271 | | |
| 272 | | === Groups === #Groups |
| 273 | | |
| 274 | | Navigate to '''Groups''' to browse all registered organizations. You can: |
| 275 | | * Filter alphabetically or search by group name or organization name |
| 276 | | * Click any group name to see its detail page: full member list, PI (Principal Investigator), and any sub-groups (Linux groups) |
| 277 | | |
| 278 | | ---- |
| 279 | | |
| 280 | | == Navigation Reference == #Navigation |
| 281 | | |
| 282 | | The portal sidebar organizes pages into sections. The following are visible to regular authenticated users: |
| 283 | | |
| 284 | | ||= Section =||= Page =||= Description =|| |
| 285 | | || My Account || Dashboard || Profile summary, quick links, usage statistics || |
| 286 | | || Scheduler || Scheduler || Calendar-based reservation system || |
| 287 | | || || My Reservations || List and manage your upcoming reservations || |
| 288 | | || Status || Testbed Status || Node power state grid (requires active reservation) || |
| 289 | | || || RF Matrix (SB4) || RF attenuation matrix control (requires SB4 reservation) || |
| 290 | | || Directory || Users || Browse all registered users || |
| 291 | | || || Groups || Browse all organizations and their members || |
| 292 | | |
| 293 | | Additional sections appear for PI/Group Admins (group member management) and Global Admins (user/group approval, scheduler management, inventory, and more). |
| 294 | | |
| 295 | | The top-right corner shows your name with a dropdown menu for '''Edit Profile''', '''SSH Keys''', and '''Log Out'''. |
| 296 | | |
| 297 | | ---- |
| 298 | | |
| 299 | | == Tips and Troubleshooting == #Tips |
| 300 | | |
| 301 | | * '''Mobile friendly''' -- on small screens, the sidebar collapses into a hamburger menu accessible from the top-left |
| 302 | | * '''Hover for help''' -- each sidebar link has a small info icon; hover over it to see a tooltip describing the page |
| 303 | | * '''Keyboard shortcuts''' -- press Escape to close any modal dialog |
| 304 | | * '''Timezone awareness''' -- the scheduler shows times in your local timezone by default, with UTC and COSMOS Eastern Time references in the clock bar |
| 305 | | * '''Time format''' -- use the 12h/24h toggle button on the scheduler to switch between AM/PM and 24-hour format; your preference is remembered |
| 306 | | * '''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 |
| 307 | | * '''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 |
| 308 | | * '''Key not working''' -- make sure you uploaded the ''public'' key (`.pub` file), not the private key. The portal validates the format on upload. |
| 309 | | * '''Can't see status pages''' -- status pages only appear when you have a current or upcoming reservation (within 24 hours) |
| 310 | | |
| 311 | | ---- |
| 312 | | |
| 313 | | == External Resources == #Resources |
| | 83 | == External Resources == |
