Repository navigation
Logging In
Quick Reference
Username + Password → TOTP Code → Dashboard
Navigate to the Veyport URL and you will see the login page.
Enter your username and password, then click Sign In.
If the username or password is wrong, you will see an error message. After 5 failed attempts in one minute, login is temporarily blocked from your IP address. Wait a minute and try again.
Separately, after too many consecutive failed attempts against the same account (the default is 5), Veyport locks that account and the page shows "account temporarily locked — try again later". Wait for the lock to lift - by default 15 minutes - or ask an administrator to unlock it, then try again. A correct password does not bypass an active lock.
Two other messages can appear here instead of the usual wrong-password error, both before your password is even checked:
- "account disabled — contact an administrator" - an administrator has turned this account off. Only an administrator can turn it back on.
- "account dormant — contact an administrator" - the account has gone unused (no sign-in and no API-token use) for longer than the hub's dormancy policy. An administrator can use Reactivate to restart its dormancy clock. If the account is locked too, it remains locked until separately unlocked; disabled accounts use Enable.
After a correct password, Veyport will ask for your two-factor authentication code.
Open your authenticator app and find the Veyport entry. Enter the current 6-digit code shown in the app.
The code changes every 30 seconds. If the code is rejected, check that the time on your phone is correct (TOTP codes are time-based) and try the next code when the timer resets.
Click Verify to complete login.
If an administrator issued you a temporary password for an existing account, enter that password
and your existing TOTP code. Veyport then allows only the required password replacement or
cancellation; it does not issue normal access while the temporary password is in effect. Complete
the replacement in the browser, then sign in again with the new password and the same TOTP. The
vey CLI cannot finish this browser recovery step. Accounts that do not yet have TOTP continue
through the first-login enrollment flow.
Veyport enforces two-factor authentication (2FA) for every account with no exceptions. The flow works as follows:
- Password verification - You submit your username and password. If correct, the server issues a short-lived session token that is only valid for the TOTP step.
- TOTP verification - You enter the 6-digit code from your authenticator app. The server verifies the code against your stored TOTP secret.
- Session issued - Once both factors are verified, the server issues a full session cookie. You are redirected to the Fleet Dashboard, or returned to the validated application launch page if you started from an application link. That return is restricted to the Veyport application launch route.
If either step fails, no session is created. The two-step process ensures that a compromised password alone is not enough to gain access.
If your administrator has enabled LDAP directory integration, you can sign in with your directory username and password (for example, your FreeIPA or Active Directory credentials) on the same login page - there is no separate "LDAP login" button.
How it works:
- You enter your directory username and password. Veyport verifies them against the directory.
- On your first sign-in, Veyport automatically creates your account. Your role (Admin, Auditor, or Viewer) and terminal eligibility come from your directory group memberships - there is nothing to request or configure yourself.
- You complete the same mandatory 2FA enrollment as local users. Directory authentication replaces the password step, never the TOTP step.
A few things to know:
- If you belong to groups mapped to more than one role, you receive the highest-privilege role.
- If you are not in any mapped group, sign-in is rejected - ask your admin to add you to the right directory group.
- Directory password changes happen in your directory (not in Veyport); the Change Password option in Settings does not apply to LDAP accounts.
- If the directory is unreachable, directory sign-ins fail but local accounts (including local admins) are unaffected.
Admins configure directory integration in Settings under the Directory tab.
Every completed sign-in - web or the vey CLI - creates a session on the hub, and that session
has two limits, both administrator-configurable in Settings → Users → Account policy:
- Idle timeout - the default is 15 minutes for web sessions and 45 minutes for CLI sessions. If no authenticated session request reaches the Hub for this long, the session expires. The Hub uses the session kind recorded at sign-in to select the limit. Signed-in pages send throttled session checks after recent keyboard, pointer, input, touch, or scroll interaction in a visible tab, including inside dialogs. These checks run independently of data polling and have a network timeout. They stop when the tab is hidden or interaction ends. Data polling also counts as activity; a visible page alone still does not guarantee the Hub is reachable.
- Maximum session (default 12 hours) - a session cannot be extended past this no matter how active you are. It is set when you sign in and never moves, even across activity that would otherwise reset the idle clock.
Either limit can be turned off by an administrator (set to 0), and each is enforced
independently - reaching either one ends the session the same way.
An established browser terminal also rechecks its original owning session every second and closes when that session expires or ends, including changes made by another Hub process. Terminal output alone does not refresh the idle clock.
These limits govern authenticated session requests. An SSH command that is already running continues if its CLI session later expires from inactivity; the next CLI request requires a new sign-in. SSH command authorization and explicit account or access revocation remain separate.
When a session expires or is ended - by either limit, by an administrator, or by using Sign out
other sessions on the Profile tab (see Settings) - the next request is refused with "session
expired — sign in again" (timed out) or "session ended — sign in again" (deliberately ended),
and a browser is returned to this sign-in page. The vey CLI prints the same message and exits
with its authentication-failure status; run vey login again.
Routine token refresh replaces the refresh token for the session that made the request. It does not sign out other browser, CLI, or device sessions, and an access token that has not expired remains valid. Logout, session expiry, account or security changes, and explicit revocation still end the sessions they apply to.
- You were idle past the timeout. The session's idle clock ran out (default 15 minutes for web, 45 minutes for CLI). Sign in again; if this happens too often for your workflow, ask an administrator whether that session kind's idle timeout can reasonably be increased.
- You'd been signed in a long time. The absolute session limit (default 12 hours) was reached regardless of activity. Sign in again - there's nothing to configure on your end.
- An administrator ended your session. Either one specific session (from the Sessions panel on your account) or everything at once (Log out everywhere, or disabling your account). Sign in again; if your account was disabled, see Troubleshooting instead.
- You signed yourself out elsewhere. Using Sign out other sessions on your own Profile tab ends every session except the one you used to click it.
- The hub was just upgraded to a release with this feature. See the note below.
See Settings for viewing and managing your own sessions, and Troubleshooting for more.
The first time a hub is upgraded to a release with server-side session records, every session that existed before the upgrade is treated as invalid - there's no record for it to check against. Every user, web and CLI, is asked to sign in once after the upgrade. This is a one-time event, not a recurring inconvenience; sessions created after the upgrade behave exactly as described above.
Veyport does not have a "forgot password" email flow. For a Local account, ask an administrator to issue a temporary password in Settings > Users and share it with you privately. Use it with your existing TOTP, complete the required password replacement in a browser, then sign in again. For an LDAP account, contact a directory administrator to reset the password in the directory and complete any required directory password change there before signing in to Veyport. Veyport administrators do not necessarily administer the directory.
You cannot log in without your TOTP code. Ask an admin to disable your 2FA from the Settings > Users tab. Once an admin disables your 2FA, you can log in with just your password and will be prompted to set up a new authenticator.
Disabling or resetting MFA revokes existing browser, API, application and SSH authority. Existing terminal shells close on credential revalidation, normally within about one second. Enroll MFA again and obtain a new SSH certificate before opening another SSH shell.
If you are the only admin and you have lost your authenticator, someone with shell access to the server must run the break-glass reset command:
./bin/veyport admin reset-totp --username <your-username> --db veyport.dbFor a local account, this resets TOTP and installs a temporary password using the configured expiry, which is printed to the terminal. Enroll TOTP and choose a fresh permanent password before it expires. Recent permanent passwords remain blocked, and existing sessions and credentials are revoked. LDAP accounts must recover their directory credentials through a directory administrator.
For a protected account, the shell reset audit must remain available until recovery completes. Audit retention preserves this record while its recovery grant is unexpired, even when the audit retention period is shorter. If the record is directly deleted or invalidated, ask the shell operator to reset again.
- Make sure you are entering the code for the Veyport entry in your authenticator, not a different service.
- TOTP codes are time-sensitive. Check that your phone's clock is set to automatic/network time.
- There is a small window of tolerance (one 30-second period before and after the current code). If the code is still rejected, contact your admin.
Contact whoever manages the Veyport server. They will need to run the CLI break-glass command (see above) to restore access.
See Troubleshooting for the difference between the per-IP rate limit and the per-account lock, and how long each takes to clear - or ask an administrator to unlock the account immediately.
These are separate from a lock and do not clear on their own. See Troubleshooting for what each means and how an administrator restores access.
See Why was I signed out? above for the possible causes (idle timeout, absolute session limit, an administrator ending your session, your own "Sign out other sessions", or a post-upgrade one-time re-sign-in), and Troubleshooting for more detail.
For more login-related solutions, see Troubleshooting.