Complete Portivo handbook

A source-backed operating manual for planning, installing, securing, administering and using Portivo Control Center in production ALE OmniSwitch environments.

1. Product scope and operating model

Portivo is a self-hosted network-operations control plane for compatible Alcatel-Lucent Enterprise OmniSwitch fleets using AOS 6 and AOS 8. The browser talks to one FastAPI application. The application enforces authentication and authorization, stores durable operational records in SQLite, and reaches managed switches through SSH. UPS monitoring uses SNMPv3 through registered power drivers. It does not replace the switch configuration database, an enterprise identity provider, a time-series platform or a configuration-management backup product.

The platform is intentionally evidence-driven. A visual state is described as live only when a current collection path supports that statement. Cached state is labelled by its observation time. Unsupported commands reduce coverage rather than being interpreted as a fault. Configuration-changing workflows require a preview, an authorized identity and a durable Job record.

2. Production planning

Management placement

Place the server in a trusted management network with routed reachability to every managed switch on SSH and to every managed UPS on SNMPv3. User browsers require HTTPS access to the Portivo service. Restrict direct access to the application port at the host or network firewall and expose it through a reverse proxy when users connect across a LAN.

Capacity and concurrency

Capacity depends more on fleet latency and operation frequency than database size. The default cross-switch worker limit is bounded, while every switch has its own serialized lane. Start with the defaults. Increase concurrency only after measuring CPU, memory, SSH establishment time and switch control-plane load. Find Device uses its own bounded search concurrency because discovery is read-only but can touch many devices.

Accounts and ownership

Define at least two named platform administrators, a service owner, an OS owner and a backup owner. Do not share the bootstrap administrator. Decide which network accounts may authenticate through switches, who approves Runbooks, who owns the Automation credential, and who can persist running configuration to flash. Record an emergency process for revoking sessions and disabling schedules.

Pre-installation checklist

• Stable hostname, static address and correct forward/reverse DNS.
• Accurate system time and an IANA platform timezone.
• Firewall paths for browser HTTPS, switch SSH and UPS SNMPv3.
• Trusted TLS certificate at the reverse proxy.
• Dedicated storage location for the database and protected backups.
• A long random application secret generated before first production start.
• Test switches representing every AOS family and major model in scope.

3. Installation and first boot

Use the matching signed Windows or Linux installer from the release package. Production installers install the locked dependencies and configure service-based startup. Preserve the complete release package and checksum file for the change record. Do not combine files from different revisions.

Windows sequence

1. Verify the release checksums before extraction.
2. Run the installer from an elevated PowerShell session.
3. Choose a service location outside temporary or user-profile folders.
4. Provide the bootstrap administrator password through the secure prompt.
5. Confirm the Windows service starts and remains running after a restart.
6. Open the health endpoint locally, then validate access through the reverse proxy.

Linux sequence

1. Verify checksums and unpack into a controlled staging directory.
2. Run the installer with the required administrative privileges.
3. Confirm the dedicated service account owns only the application data it needs.
4. Inspect the installed systemd unit and its sandbox controls.
5. Start the service, inspect its status, and test the local health endpoint.
6. Configure the reverse proxy, HTTPS certificate and WebSocket forwarding.

4. Network, proxy and HTTPS

The reverse proxy must forward normal HTTP requests and preserve WebSocket upgrades for the interactive terminal. Set the public URL scheme to HTTPS only after TLS terminates at a trusted proxy. Trust forwarded headers only from explicit proxy addresses; otherwise a client could influence security-sensitive request metadata.

Validation path

1. From the server, verify the application health endpoint on the local listener.
2. From the proxy, verify upstream reachability.
3. From a management client, verify HTTPS certificate chain, hostname and redirect behavior.
4. Sign in and open a terminal to confirm WebSocket forwarding.
5. Inspect cookies and confirm secure transport behavior matches the configured public scheme.
6. Block direct client access to the application port and retest the public URL.

If pages load but Terminal does not, treat proxy upgrade headers and timeout settings as the first diagnostic branch. If sign-in loops occur only through the proxy, verify scheme handling, trusted proxy IPs and cookie security before changing authentication settings.

5. Initial configuration

1. Sign in with the bootstrap administrator and immediately confirm the platform timezone.
2. Create named administrative access and retain the bootstrap identity only for controlled recovery.
3. Select Full monitoring or Management only. In Management only, on-demand tools remain available but background monitoring workers pause.
4. Add Sites and Groups through the switch inventory structure you intend to use for authorization and notification routing.
5. Add one representative test switch without storing a shared interactive password.
6. Verify connectivity with a personal SSH session, then collect Live Ports and run a read-only action.
7. Create monitoring credentials only for services that require them and test each credential against an explicit target.
8. Configure backup ownership before importing the production fleet.

6. Authentication, sessions and access control

Portivo supports local application identities and SSH-backed network-user authentication. A network user's SSH password is protected only for the active server-process session and is not converted into a shared stored credential. Personal manual operations therefore remain attributable to the signed-in user.

Role evaluation

Authorization combines role capabilities with Site and Group scope. A visible page does not by itself authorize an action; the backend checks the exact capability again. Built-in roles cover Administrator, Power User, Site Administrator, Operator, Helpdesk and Read Only patterns. Custom Roles allow administrators to assemble exact rights without assigning blanket administration.

Least-privilege design

• Give Read Only access to users who only inspect state and reports.
• Separate operational execution from user, role, credential and platform administration.
• Restrict Site Administrators to their actual estate.
• Grant Terminal access only when direct CLI access is part of the user's job.
• Treat Runbook approval, schedule management, device reload and persistent save as high-trust capabilities.
• Review sessions and user mappings after personnel or responsibility changes.

Login throttling is progressive and happens before expensive authentication work. Repeated failures should be investigated rather than “fixed” by disabling throttling. Administrators can revoke active sessions from the administration workspace.

7. Switch inventory and device lifecycle

A switch record contains its management identity, Site, Group, expected platform profile and monitoring state. The management address must uniquely identify the target. Use names that match operational conventions and avoid placing secrets in aliases, descriptions or import files.

Adding a switch

1. Confirm SSH reachability from the Portivo host.
2. Select the correct Site and Group.
3. Enter the management address and expected AOS profile.
4. Use Verify/Test with a personal credential.
5. Review learned identity rather than assuming the model from a label.
6. Collect Live Ports and compare a sample against the switch CLI.
7. Enable monitoring only after the identity and scope are correct.

Bulk import

Download the current template, preserve its headers, validate address uniqueness and use a small pilot batch first. Import validates rows; it should not be used as a blind replacement for change review. After import, filter by Site and perform representative identity and port-inventory checks.

Editing and deletion

Changing a management address or platform profile can invalidate learned capability evidence and cached observations. Deletion removes the managed object from active inventory; retain required Job, audit and backup evidence according to policy before removing it. Do not delete and recreate devices merely to clear a transient monitoring state.

8. Dashboard and health interpretation

The Dashboard is an attention surface, not a substitute for investigation. Managed-switch totals, availability, Jobs and power attention are permission-filtered. In Management only mode, current-health cards explicitly show that monitoring is paused and retain last-known context without presenting it as live.

Responding to attention

1. Confirm whether the indicator is live, delayed or paused.
2. Open the affected object and read the latest observation time.
3. Compare correlated evidence: switch reachability, stack state, UPS state and recent Jobs.
4. Use an on-demand diagnostic or read-only audit before applying a change.
5. Record the final cause and action through the normal Job/audit workflow.

An Offline indicator is produced by a lightweight management-path probe. It does not prove hardware failure. Routing, firewall, SSH listener, maintenance and upstream power can produce the same symptom. Power correlation is reported only where an assigned UPS and its last-known state support that conclusion.

9. Live Ports, front panels and port details

Live Port Inventory opens a serialized SSH collection for one switch and normalizes administrative state, physical link, alias, VLAN, media and PoE data. Supported models render a logical chassis/front-panel layout; unknown or non-physical interfaces are kept separate instead of being forced into a port map.

Reading state correctly

• Administratively enabled, link down: no carrier is currently detected; check endpoint, patching, optics and remote state.
• Administratively disabled: physical link absence is expected until configuration changes.
• Multiple learned MACs: may indicate an uplink, phone-plus-workstation, access point or unmanaged downstream switch.
• PoE enabled with zero draw: can be normal, but combined with an expected powered endpoint it requires cable, class and device checks.
• Cached observation: use Refresh before acting when timing matters.

Safe port actions

Alias changes, interface restart and PoE restart enter the same preview and Job system as other operations. Confirm the physical endpoint and redundancy impact before restarting a production port. Never use a bulk restart as a discovery technique.

10. Find Device

Find Device accepts MAC, IP, hostname, UNP username/profile and VLAN-oriented queries. MAC is the strongest endpoint identity. IP searches correlate ARP, forwarding and UNP evidence; when a static IP has no current neighbor entry, a bounded active probe and retry may be used. Candidate-switch LLDP evidence helps distinguish an edge port from an upstream observation.

Result interpretation

Read the evidence and confidence fields, not only the first row. A result observed on an uplink is not presented as the endpoint's physical location. Multi-MAC ports are not merged merely because observations share the same interface. Last-known location is a single bounded record per MAC, not a time-series history.

Recommended procedure

1. Normalize the identifier and start with MAC when available.
2. Wait for the fleet search to complete or clearly report partial coverage.
3. Inspect candidate type, LLDP context, learned MAC and observation age.
4. Open the candidate port and run Port Troubleshooter.
5. Only then choose a corrective action.

11. Port Troubleshooter

The troubleshooter is read-only and scoped to one physical port. It collects interface state, media, counters, PoE, learned MACs, UNP identity and LLDP evidence in one serialized session. Parsers are conservative: absent or unfamiliar output is shown as Not reported instead of being inferred.

12. Operations, preview and execution

The action catalog separates read-only collection, configuration changes, Portivo-orchestrated workflows, model-dependent actions and unsupported operations. The backend resolves the action against the device's detected AOS family and learned capability evidence. It does not probe configuration-changing syntax experimentally.

Execution lifecycle

1. Select an action and eligible targets.
2. Supply only parameters required by that action.
3. Generate a preview and read every target-specific command.
4. Confirm the target count, Site/Group spread and risk classification.
5. Execute to create a Job and one Job Item per target.
6. Monitor progress, output and heartbeat evidence.
7. Review pending configuration when the change affects running state.
8. Persist configuration explicitly only after validation.

Different switches can execute concurrently, but work on the same device remains FIFO. One live operation owns its SSH connection and device lease for the complete transaction. This prevents a second Job or terminal from overtaking a partially completed workflow.

Unsaved configuration

Configuration changes are recorded as pending rather than written to flash after every action. The Unsaved Configuration workflow groups affected devices. Validate service, then persist the intended switches. AOS 8 and AOS 6 use their appropriate save flows; the device lane remains held through prompt stabilization and the post-save cooldown.

13. Jobs, cancellation, retry and evidence

A Job is the durable execution container; Job Items hold per-target results. Statuses distinguish queued, running, cancelling, completed, failed, cancelled and interrupted work. On application startup, work left active by an earlier process is reconciled to Interrupted while completed target evidence is preserved.

Cancellation

Cancellation is cooperative. It prevents additional safe work and records the transition, but cannot guarantee that a CLI command already accepted by a switch is undone. Review each item after cancellation and verify device state.

Retry

Retry creates traceable new work for eligible failed/interrupted targets and rechecks current authorization and action eligibility. Do not retry an authentication or syntax failure repeatedly without correcting the cause. A learned explicit capability rejection protects the device from repeated incompatible probes until its identity changes.

Evidence handling

Use filters to locate Jobs by time, action, status and target. Export the provided report when a change record requires evidence. Passwords and interactive terminal content are not stored in Job records. Retention and pruning must follow the organization's audit requirements.

14. Runbooks and scheduled automation

A Runbook is a reusable workflow with typed COMMAND, WAIT and VERIFY steps, optional variables and an execution policy. Draft and Approved are security states. Editing an approved definition returns it to Draft. Before execution, variables are validated and the complete rendered workflow is copied into the Job payload as an immutable snapshot.

Authoring standard

• State the purpose, owner, prerequisites and expected postcondition.
• Keep variables typed, bounded and human-readable.
• Use read-only verification before and after a change.
• Set target and concurrency limits that match actual blast radius.
• Reject ambiguous or empty variable values.
• Test against a representative non-critical target before approval.

Schedules

Schedules specify when and where an approved automation action runs. They use a dedicated encrypted service credential, not an operator's interactive password. Eligibility and target limits are re-evaluated when a scheduled Job is created, so a growing Site/Group cannot silently exceed policy. Disabling a schedule prevents future creation; it does not rewrite completed history.

UNP and VLAN safeguards

Fix UNP and VLAN maintenance use centralized safeguard policies. Protected ports, guest-profile keywords, voice/IPTV exclusions, LAG/LLDP/MAC evidence and impact limits are evaluated before a disruptive step and revalidated immediately before execution. A blocked target is a safety result, not an error to bypass.

15. Monitoring and notifications

Full monitoring can independently enable switch availability, stack health, UPS monitoring and incident detection. Management only pauses the background workers while preserving credentials, baselines, assignments, routing and history. On-demand Operations, Find Device, audits and administration remain usable.

Switch reachability

The background health worker performs a lightweight TCP probe to the configured SSH service. Confirmation thresholds and retry timing prevent a single transient failure from becoming an incident. Long-offline targets are polled at a lower rate to control load.

Destinations and routing

Microsoft Teams/Power Automate, Slack, Discord and Generic JSON destinations can coexist. Endpoint URLs are encrypted at rest and are not returned in clear text after save. Each destination has event subscriptions and Site/Group scope. One incident can fan out to multiple independent delivery rows.

Delivery semantics

The outbox is persisted before network delivery. Temporary failures use bounded retry. A failed destination does not block another. If a target recovers before an offline message is delivered, the pending outage can be cancelled. Recovery is sent only to destinations that received the corresponding outage and still subscribe to recovery.

16. Power and UPS operations

UPS assets are stored once and assigned to protected switches. SNMPv3 profiles are reusable encrypted monitoring credentials. Drivers include standards-based RFC 1628 and vendor-aware paths; Auto detect uses live identity evidence while an explicit driver can be selected for known equipment.

Onboarding a UPS

1. Create and verify an SNMPv3 authPriv credential against the UPS.
2. Add the UPS with Site, address and driver selection.
3. Refresh Details and review which metrics were actually returned.
4. Assign only switches physically protected by that UPS and in the appropriate Site.
5. Run a scan and verify the stored last-observation time.
6. Test notification routing without simulating a real outage on production power.

Detailed telemetry groups Identity, Battery, Input, Output, Bypass, Environment, Diagnostics and Monitoring values. Unsupported values are omitted rather than displayed as meaningful “Unknown” metrics. Regular polling stays lightweight; detailed collection is on demand.

Power-cause correlation is evidence-based. Simultaneous loss of a UPS management address and a switch does not prove UPS hardware failure. Probable or high-confidence correlation requires an assignment and supporting UPS state.

17. Fleet Audits and reports

Fleet Audits are explicit, read-only assessments with bounded cross-device concurrency and one SSH session per audit/device. Available assessments cover thermal health, cooling, power supplies, PoE capacity, interface errors, port stability, managed uplinks, persistent configuration and full switch health.

Running an audit

1. Select the audit objective before selecting targets.
2. Choose representative scope; do not default to the entire fleet.
3. Confirm credential/session readiness and maintenance context.
4. Run and allow every item to reach a terminal status.
5. Review evidence coverage and compatibility errors before severity.
6. Export the PDF and attach it to the operational record when required.

Findings store normalized evidence, severity, coverage and command-level compatibility errors rather than raw credential material. Missing commands reduce coverage. Numeric temperatures without verified device thresholds are reported as observations, not compared against invented limits. Full Switch Health scores only the evidence actually available.

18. Backup, restore, upgrade and maintenance

The SQLite database contains inventory, role mappings, encrypted credential material, settings, Jobs, audit data, incidents and the latest observations. Treat every backup as sensitive. The built-in download streams a consistent backup without reading the complete file into application memory.

Backup procedure

1. Confirm the service and database are healthy.
2. Download the built-in backup using an authorized administrator session.
3. Store it in encrypted, access-controlled backup storage.
4. Record release version, timestamp, operator and checksum.
5. Test restoration on an isolated instance at a defined interval.

Restore procedure

1. Schedule downtime and capture a final backup.
2. Confirm the target application version is compatible with the backup.
3. Use the controlled import path and allow validation to complete.
4. Restart if instructed and check health/build identity.
5. Verify users, roles, inventory, settings, schedules and recent history.
6. Test one representative device and credential without launching bulk work.

Upgrade procedure

Read the release notes, verify checksums, take a tested backup, pause schedules, finish or cancel active Jobs, and preserve the prior installer. Apply the installer using its supported repair/upgrade path. Afterward verify service health, database migrations, UI build identity, authentication, representative monitoring, one read-only Job and WebSocket terminal behavior. Re-enable schedules only after acceptance.

Pruning

Maintenance pruning bounds completed operational history according to the configured retention behavior. Export evidence required by external policy before pruning. Never use database-file deletion as a maintenance shortcut.

19. Security hardening baseline

• Use HTTPS and restrict access to trusted management networks.
• Set a unique long application secret and protect environment files.
• Trust proxy headers only from explicit reverse-proxy addresses.
• Run under the installer-created low-privilege service identity.
• Restrict database, logs, configuration and backups at the filesystem layer.
• Prefer personal SSH sessions for manual activity and a separate least-privilege Automation account for schedules.
• Use SNMPv3 authPriv; avoid weaker modes unless a documented legacy constraint requires them.
• Review roles, scope, sessions, destinations and schedules periodically.
• Keep the host OS and Portivo release current through a tested change process.
• Do not publish application, database or backup ports to the public Internet.

Generic webhook targets are HTTPS-only and reject localhost, private, link-local and other non-public destinations to reduce server-side request forgery risk. Credential endpoints avoid returning saved secrets. Application authorization is enforced server-side even when the browser hides an unavailable control.

20. Troubleshooting playbook

Evidence collection order

1. Record exact time, user, URL/page, target and visible status.
2. Determine whether the issue affects one user, one target, one Site or the whole service.
3. Check the least invasive health and read-only evidence first.
4. Correlate application status, Job history, audit log and device-side state.
5. Change one variable at a time and preserve before/after evidence.
6. After recovery, document root cause, corrective action and prevention.

21. Operating routines

Daily

• Review Infrastructure Attention, active/failed Jobs and open incidents.
• Check interrupted work after service maintenance.
• Confirm scheduled automation completed within expected scope.
• Investigate persistent Offline assets and notification delivery failures.

Weekly

• Review unsaved configuration and persist or deliberately clear the operational plan.
• Run targeted health audits on critical Sites.
• Review UPS assignments and stale telemetry.
• Check backup completion and storage protection.

Monthly or quarterly

• Review users, roles, scopes, active sessions and service credentials.
• Test backup restoration in isolation.
• Review Runbook approvals, schedules, safeguard policies and notification routing.
• Plan release upgrades and host patching.
• Validate representative AOS 6, AOS 8 and UPS driver behavior after infrastructure changes.

22. Exact references