api

package

v0.4.0 Latest Latest Go to latest Published: Jun 12, 2026 License: Apache-2.0 Imports: 55 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/srl-labs/clab-api-server

Links

Documentation ¶

Rendered for

Overview ¶

internal/api/auth_handlers.go

internal/api/clab_service.go

internal/api/events_handlers.go

internal/api/health_handlers.go

internal/api/helpers.go

internal/api/info_handlers.go

internal/api/lab_handlers.go

internal/api/logs_handlers.go

internal/api/routes.go

internal/api/ssh_handlers.go

internal/api/tools_handlers.go

internal/api/topology_handlers.go

internal/api/user_handlers.go

Index ¶

func AuthMiddleware() gin.HandlerFunc
func BuildPacketflixCaptureHandler(c *gin.Context)
func CORSMiddleware() gin.HandlerFunc
func ChangeUserPasswordHandler(c *gin.Context)
func CheckVersionHandler(c *gin.Context)
func CreateCAHandler(c *gin.Context)
func CreateUserHandler(c *gin.Context)
func CreateVethHandler(c *gin.Context)
func CreateVxlanHandler(c *gin.Context)
func CreateWiresharkVncSessionsHandler(c *gin.Context)
func CreateWorkspaceDirectoryHandler(c *gin.Context)
func DeleteAllWiresharkVncSessionsHandler(c *gin.Context)
func DeleteCustomNodeHandler(c *gin.Context)
func DeleteGlobalIconHandler(c *gin.Context)
func DeleteTopologyFileHandler(c *gin.Context)
func DeleteUserHandler(c *gin.Context)
func DeleteVxlanHandler(c *gin.Context)
func DeleteWiresharkVncSessionHandler(c *gin.Context)
func DeleteWorkspaceFileHandler(c *gin.Context)
func DeployLabArchiveHandler(c *gin.Context)
func DeployLabHandler(c *gin.Context)
func DeployTopologyHandler(c *gin.Context)
func DestroyLabHandler(c *gin.Context)
func DisableTxOffloadHandler(c *gin.Context)
func ExecCommandHandler(c *gin.Context)
func GenerateLabDrawioHandler(c *gin.Context)
func GenerateTopologyHandler(c *gin.Context)
func GetCaptureManager() *capture.Manager
func GetClabService() *clab.Service
func GetCustomNodesHandler(c *gin.Context)
func GetEdgeSharkStatusHandler(c *gin.Context)
func GetNodeBrowserPortsHandler(c *gin.Context)
func GetNodeLogsHandler(c *gin.Context)
func GetRunningLabAnnotationsHandler(c *gin.Context)
func GetRunningLabYamlHandler(c *gin.Context)
func GetTerminalSessionHandler(c *gin.Context)
func GetTopologyFileHandler(c *gin.Context)
func GetUserDetailsHandler(c *gin.Context)
func GetVersionHandler(c *gin.Context)
func GetWiresharkVncSessionReadyHandler(c *gin.Context)
func GetWorkspaceFileHandler(c *gin.Context)
func HeadTopologyFileHandler(c *gin.Context)
func HealthCheckHandler(c *gin.Context)
func ImportTopologyFromURLHandler(c *gin.Context)
func InitCaptureManager()
func InitHealth(version string)
func InitSSHManager()
func InitTerminalManager()
func InspectInterfacesHandler(c *gin.Context)
func InspectLabHandler(c *gin.Context)
func InstallEdgeSharkHandler(c *gin.Context)
func LabGoTTYShareHandler(c *gin.Context)
func LabSSHXShareHandler(c *gin.Context)
func ListGlobalIconsHandler(c *gin.Context)
func ListLabIconsHandler(c *gin.Context)
func ListLabsHandler(c *gin.Context)
func ListRuntimeImagesHandler(c *gin.Context)
func ListSSHSessionsHandler(c *gin.Context)
func ListTopologiesHandler(c *gin.Context)
func ListUsersHandler(c *gin.Context)
func ListWorkspaceTreeHandler(c *gin.Context)
func LoginHandler(c *gin.Context)
func PauseNodeHandler(c *gin.Context)
func ProxyWiresharkVncSessionHandler(c *gin.Context)
func PullRuntimeImageHandler(c *gin.Context)
func PutCustomNodesHandler(c *gin.Context)
func PutRunningLabAnnotationsHandler(c *gin.Context)
func PutRunningLabYamlHandler(c *gin.Context)
func PutTopologyFileHandler(c *gin.Context)
func PutWorkspaceFileHandler(c *gin.Context)
func ReconcileLabIconsHandler(c *gin.Context)
func RedeployLabHandler(c *gin.Context)
func RemoveRuntimeImageHandler(c *gin.Context)
func RenameTopologyFileHandler(c *gin.Context)
func RenameWorkspaceFileHandler(c *gin.Context)
func RequestSSHAccessHandler(c *gin.Context)
func RequestTerminalSessionHandler(c *gin.Context)
func ResetNetemHandler(c *gin.Context)
func RestartLabNodesHandler(c *gin.Context)
func RestartNodeHandler(c *gin.Context)
func RunLabFcliHandler(c *gin.Context)
func SaveCustomNodeHandler(c *gin.Context)
func SaveLabConfigHandler(c *gin.Context)
func SetClabService(svc *clab.Service)
func SetDefaultCustomNodeHandler(c *gin.Context)
func SetNetemHandler(c *gin.Context)
func SetupRoutes(router *gin.Engine)
func ShowNetemHandler(c *gin.Context)
func ShutdownCaptureManager()
func ShutdownSSHManager()
func ShutdownTerminalManager()
func SignCertHandler(c *gin.Context)
func StartLabNodesHandler(c *gin.Context)
func StartNodeHandler(c *gin.Context)
func StopLabNodesHandler(c *gin.Context)
func StopNodeHandler(c *gin.Context)
func StreamEventsHandler(c *gin.Context)
func StreamTerminalSessionHandler(c *gin.Context)
func StreamTopologyFileEventsHandler(c *gin.Context)
func StreamWorkspaceEventsHandler(c *gin.Context)
func SystemMetricsHandler(c *gin.Context)
func TerminateSSHSessionHandler(c *gin.Context)
func TerminateTerminalSessionHandler(c *gin.Context)
func UninstallEdgeSharkHandler(c *gin.Context)
func UnpauseNodeHandler(c *gin.Context)
func UpdateUserHandler(c *gin.Context)
func UploadGlobalIconHandler(c *gin.Context)

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func AuthMiddleware ¶

func AuthMiddleware() gin.HandlerFunc

AuthMiddleware validates the JWT token from the Authorization header

func BuildPacketflixCaptureHandler ¶ added in v0.3.0

func BuildPacketflixCaptureHandler(c *gin.Context)

BuildPacketflixCaptureHandler generates packetflix URIs for capture targets. @Summary Build packetflix capture URI @Description Builds packetflix URI(s) for the provided lab interface targets (non-VNC capture mode). @Tags Capture @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" example="my-lab" @Param capture_request body models.CapturePacketflixRequest true "Packetflix capture request" @Success 200 {object} models.CapturePacketflixResponse "Packetflix capture URI payload" @Failure 400 {object} models.ErrorResponse "Invalid request" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Lab or container not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Failure 503 {object} models.ErrorResponse "EdgeShark not running" @Router /api/v1/labs/{labName}/capture/packetflix [post]

func CORSMiddleware ¶ added in v0.3.0

func CORSMiddleware() gin.HandlerFunc

CORSMiddleware enables browser access for configured origins. Origins are matched exactly against CORS_ALLOWED_ORIGINS, unless "*" is set.

func ChangeUserPasswordHandler ¶ added in v0.1.4

func ChangeUserPasswordHandler(c *gin.Context)

@Summary Change user password @Description Changes a user's password. Requires superuser privileges or the user's own account. @Tags Users @Security BearerAuth @Accept json @Produce json @Param username path string true "Username to change password for" example="john" @Param passwordChange body models.PasswordChangeRequest true "Password change details" @Success 200 {object} models.GenericSuccessResponse "Password changed successfully" @Failure 400 {object} models.ErrorResponse "Invalid request body" @Failure 401 {object} models.ErrorResponse "Unauthorized or incorrect current password" @Failure 403 {object} models.ErrorResponse "Forbidden (Not superuser or not the user's own account)" @Failure 404 {object} models.ErrorResponse "User not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users/{username}/password [put]

func CheckVersionHandler ¶

func CheckVersionHandler(c *gin.Context)

@Summary Check containerlab updates @Description Checks whether a newer containerlab release is available. @Tags Version @Security BearerAuth @Produce json @Success 200 {object} models.VersionCheckResponse "Result of the version check" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Router /api/v1/version/check [get]

func CreateCAHandler ¶

func CreateCAHandler(c *gin.Context)

@Summary Create certificate authority (CA) @Description Creates a CA certificate and private key. Requires superuser privileges. @Description @Description **Notes** @Description - Files are stored in the user's `~/.clab/certs/<ca_name>/` directory on the server. @Tags Tools - Certificates @Security BearerAuth @Accept json @Produce json @Param ca_request body models.CACreateRequest true "CA Generation Parameters" @Success 200 {object} models.CertResponse "CA created successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 500 {object} models.ErrorResponse "Internal server error (filesystem, clab execution)" @Router /api/v1/tools/certs/ca [post]

func CreateUserHandler ¶ added in v0.1.4

func CreateUserHandler(c *gin.Context)

@Summary Create user @Description Creates a new system user. Requires superuser privileges. @Tags Users @Security BearerAuth @Accept json @Produce json @Param user body models.UserCreateRequest true "User creation details" @Success 201 {object} models.GenericSuccessResponse "User created successfully" @Failure 400 {object} models.ErrorResponse "Invalid request body" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 409 {object} models.ErrorResponse "User already exists" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users [post]

func CreateVethHandler ¶

func CreateVethHandler(c *gin.Context)

@Summary Create vEth pair @Description Creates a virtual Ethernet (vEth) pair between two endpoints (container, host, bridge, or ovs-bridge). Requires superuser privileges. @Tags Tools - vEth @Security BearerAuth @Accept json @Produce json @Param veth_request body models.VethCreateRequest true "vEth Creation Parameters" @Success 200 {object} models.GenericSuccessResponse "vEth pair created successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters (endpoints, MTU)" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 500 {object} models.ErrorResponse "Internal server error (clab execution failed)" @Router /api/v1/tools/veth [post]

func CreateVxlanHandler ¶

func CreateVxlanHandler(c *gin.Context)

@Summary Create VxLAN tunnel @Description Creates a VxLAN tunnel interface and sets up tc rules for traffic redirection. Requires superuser privileges. @Tags Tools - VxLAN @Security BearerAuth @Accept json @Produce json @Param vxlan_request body models.VxlanCreateRequest true "VxLAN Creation Parameters" @Success 200 {object} models.GenericSuccessResponse "VxLAN tunnel created successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters (remote, link, id, port, etc.)" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 500 {object} models.ErrorResponse "Internal server error (clab execution failed)" @Router /api/v1/tools/vxlan [post]

func CreateWiresharkVncSessionsHandler ¶ added in v0.3.0

func CreateWiresharkVncSessionsHandler(c *gin.Context)

CreateWiresharkVncSessionsHandler launches wireshark noVNC sessions for capture targets. @Summary Create Wireshark VNC capture session(s) @Description Creates one or more Wireshark noVNC capture sessions for the specified lab interface targets. @Tags Capture @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" example="my-lab" @Param capture_request body models.CaptureWiresharkVncRequest true "Wireshark VNC capture request" @Success 200 {object} models.CaptureWiresharkVncCreateResponse "Created capture sessions" @Failure 400 {object} models.ErrorResponse "Invalid request" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Lab or container not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Failure 503 {object} models.ErrorResponse "EdgeShark not running" @Router /api/v1/labs/{labName}/capture/wireshark-vnc-sessions [post]

func CreateWorkspaceDirectoryHandler ¶ added in v0.3.4

func CreateWorkspaceDirectoryHandler(c *gin.Context)

@Summary Create lab workspace directory @Description Creates a directory inside the authenticated user's editable lab workspace root. @Tags Labs @Security BearerAuth @Accept json @Produce json @Param directory_request body models.WorkspaceDirectoryRequest true "Directory path" @Success 200 {object} models.SimpleSuccessResponse "Directory create success" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/directory [post]

func DeleteAllWiresharkVncSessionsHandler ¶ added in v0.3.0

func DeleteAllWiresharkVncSessionsHandler(c *gin.Context)

DeleteAllWiresharkVncSessionsHandler terminates all running wireshark VNC sessions owned by the current user (or all sessions for a superuser). @Summary Delete all Wireshark VNC sessions @Description Terminates all capture VNC sessions owned by the authenticated user. Superusers terminate all sessions. @Tags Capture @Security BearerAuth @Produce json @Success 200 {object} models.CaptureCloseAllResponse "Capture sessions terminated" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/capture/wireshark-vnc-sessions [delete]

func DeleteCustomNodeHandler ¶ added in v0.3.0

func DeleteCustomNodeHandler(c *gin.Context)

@Summary Delete custom node template @Description Deletes a single TopoViewer custom node template for the authenticated user. @Tags UI @Security BearerAuth @Produce json @Param name path string true "Custom node name" @Success 200 {object} models.CustomNodesResponse "Updated custom node templates" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/custom-nodes/{name} [delete]

func DeleteGlobalIconHandler ¶ added in v0.3.0

func DeleteGlobalIconHandler(c *gin.Context)

@Summary Delete global custom icon @Description Deletes a global custom TopoViewer icon from ~/.clab/icons for the authenticated user. @Tags UI @Security BearerAuth @Produce json @Param iconName path string true "Custom icon name" @Success 200 {object} models.SimpleSuccessResponse "Delete success" @Failure 400 {object} models.ErrorResponse "Invalid icon name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Icon not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/icons/{iconName} [delete]

func DeleteTopologyFileHandler ¶ added in v0.3.0

func DeleteTopologyFileHandler(c *gin.Context)

@Summary Delete lab topology file @Description Deletes a file inside the specified lab directory using a scoped relative path. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Lab name" @Param path query string true "Relative file path inside lab directory" @Success 200 {object} models.SimpleSuccessResponse "Delete success" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/file [delete]

func DeleteUserHandler ¶ added in v0.1.4

func DeleteUserHandler(c *gin.Context)

@Summary Delete user @Description Deletes a user from the system. Requires superuser privileges. @Tags Users @Security BearerAuth @Produce json @Param username path string true "Username to delete" example="john" @Success 200 {object} models.GenericSuccessResponse "User deleted successfully" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 404 {object} models.ErrorResponse "User not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users/{username} [delete]

func DeleteVxlanHandler ¶

func DeleteVxlanHandler(c *gin.Context)

@Summary Delete VxLAN tunnels by prefix @Description Deletes VxLAN tunnel interfaces that match the provided prefix (default: `vx-`). Requires superuser privileges. @Tags Tools - VxLAN @Security BearerAuth @Produce json @Param prefix query string false "Prefix of VxLAN interfaces to delete" default(vx-) example="vx-" @Success 200 {object} models.GenericSuccessResponse "VxLAN tunnels deleted successfully" @Failure 400 {object} models.ErrorResponse "Invalid prefix format" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 500 {object} models.ErrorResponse "Internal server error (clab execution failed)" @Router /api/v1/tools/vxlan [delete]

func DeleteWiresharkVncSessionHandler ¶ added in v0.3.0

func DeleteWiresharkVncSessionHandler(c *gin.Context)

DeleteWiresharkVncSessionHandler terminates a running wireshark VNC session. @Summary Delete Wireshark VNC session @Description Terminates a capture VNC session and stops the corresponding Wireshark container. @Tags Capture @Security BearerAuth @Produce json @Param sessionId path string true "Capture session ID" @Success 200 {object} models.GenericSuccessResponse "Capture session terminated" @Failure 400 {object} models.ErrorResponse "Invalid request" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/capture/wireshark-vnc-sessions/{sessionId} [delete]

func DeleteWorkspaceFileHandler ¶ added in v0.3.4

func DeleteWorkspaceFileHandler(c *gin.Context)

@Summary Delete lab workspace file @Description Deletes a file or directory inside the authenticated user's editable lab workspace root. Directories with children require recursive=true. @Tags Labs @Security BearerAuth @Produce json @Param path query string true "Relative file path inside the workspace root" @Param recursive query bool false "Delete non-empty directories recursively" @Success 200 {object} models.SimpleSuccessResponse "Delete success" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/file [delete]

func DeployLabArchiveHandler ¶

func DeployLabArchiveHandler(c *gin.Context)

@Summary Deploy lab from archive @Description Deploys a containerlab topology provided as a .zip or .tar.gz archive. @Tags Labs @Security BearerAuth @Accept multipart/form-data @Produce json @Param labArchive formData file true "Lab archive (.zip or .tar.gz)" @Param labName query string true "Name for the lab" @Param reconfigure query boolean false "Allow overwriting an existing lab" @Param maxWorkers query int false "Limit concurrent workers" @Param exportTemplate query string false "Custom Go template file for topology data export" @Param nodeFilter query string false "Comma-separated list of node names to deploy" @Param skipPostDeploy query boolean false "Skip post-deploy actions" @Param skipLabdirAcl query boolean false "Skip setting extended ACLs on lab directory" @Success 200 {object} models.ClabInspectOutput "Deployed lab details" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 409 {object} models.ErrorResponse "Conflict" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/archive [post]

func DeployLabHandler ¶

func DeployLabHandler(c *gin.Context)

@Summary Deploy lab @Description Deploys a containerlab topology. @Description @Description **Notes** @Description - The request body must include either `topologyContent` or `topologySourceUrl` (not both). @Tags Labs @Security BearerAuth @Accept json @Produce json @Param deploy_request body models.DeployRequest true "Deployment Source" @Param labNameOverride query string false "Override lab name when deploying from a URL (optional)" @Param reconfigure query boolean false "Allow overwriting an existing lab IF owned by the user" @Param maxWorkers query int false "Limit concurrent workers" @Param exportTemplate query string false "Custom Go template file for topology data export" @Param nodeFilter query string false "Comma-separated list of node names to deploy" @Param skipPostDeploy query boolean false "Skip post-deploy actions" @Param skipLabdirAcl query boolean false "Skip setting extended ACLs on lab directory" @Success 200 {object} models.ClabInspectOutput "Deployed lab details" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 409 {object} models.ErrorResponse "Conflict" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs [post]

func DeployTopologyHandler ¶ added in v0.3.0

func DeployTopologyHandler(c *gin.Context)

@Summary Deploy on-disk topology for lab @Description Deploys an on-disk topology from the authenticated user's lab directory. @Description @Description **Notes** @Description - `path` defaults to `<labName>.clab.yml` when omitted. @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Lab name" @Param path query string false "Relative topology file path inside lab directory (defaults to <labName>.clab.yml)" @Param reconfigure query boolean false "Allow overwriting an existing lab" @Param maxWorkers query int false "Limit concurrent workers" @Param exportTemplate query string false "Custom Go template file for topology data export" @Param nodeFilter query string false "Comma-separated list of node names to deploy" @Param skipPostDeploy query boolean false "Skip post-deploy actions" @Param skipLabdirAcl query boolean false "Skip setting extended ACLs on lab directory" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.ClabInspectOutput "Deployed lab details" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Topology file not found" @Failure 409 {object} models.ErrorResponse "Conflict" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/deploy [post] DeployTopologyHandler deploys an on-disk topology identified by lab name.

func DestroyLabHandler ¶

func DestroyLabHandler(c *gin.Context)

@Summary Destroy lab @Description Destroys a lab by name after verifying ownership. @Description @Description **Notes** @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Name of the lab to destroy" @Param cleanup query boolean false "Remove containerlab lab artifacts after destroy" @Param purgeLabDir query boolean false "Purge topology parent directory for managed lab paths (~/.clab or CLAB_LABS_ROOT)" @Param graceful query boolean false "Attempt graceful shutdown" @Param gracefulTimeout query string false "Override graceful shutdown timeout when graceful=true (for example 5s or 2m)" @Param keepMgmtNet query boolean false "Keep the management network" @Param nodeFilter query string false "Destroy only specific nodes" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.GenericSuccessResponse "Lab destroyed successfully" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName} [delete]

func DisableTxOffloadHandler ¶

func DisableTxOffloadHandler(c *gin.Context)

@Summary Disable TX checksum offload @Description Disables TX checksum offload on the eth0 interface of a container. Requires superuser privileges. @Tags Tools @Security BearerAuth @Accept json @Produce json @Param tx_request body models.DisableTxOffloadRequest true "Container Name" @Success 200 {object} models.GenericSuccessResponse "Offload disabled successfully" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 404 {object} models.ErrorResponse "Container not found" @Failure 500 {object} models.ErrorResponse "Internal server error or clab execution failed" @Router /api/v1/tools/disable-tx-offload [post]

func ExecCommandHandler ¶

func ExecCommandHandler(c *gin.Context)

@Summary Execute command in lab @Description Executes a command on nodes within a lab. @Tags Labs @Security BearerAuth @Accept json @Produce json @Param labName path string true "Name of the lab" @Param nodeFilter query string false "Execute only on this specific node" @Param exec_request body models.ExecRequest true "Command to execute" @Success 200 {object} models.ExecResponse "Execution result" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/exec [post]

func GenerateLabDrawioHandler ¶ added in v0.3.0

func GenerateLabDrawioHandler(c *gin.Context)

@Summary Generate draw.io graph @Description Generates a draw.io diagram from a lab topology and returns the generated XML content. @Tags Labs - Graph @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab Name" @Param drawio_request body models.DrawioGenerateRequest false "Draw.io generation options" @Success 200 {object} models.DrawioGenerateResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/graph/drawio [post]

func GenerateTopologyHandler ¶

func GenerateTopologyHandler(c *gin.Context)

@Summary Generate containerlab topology @Description Generates a containerlab topology from CLOS definitions and can optionally deploy it for the authenticated user. @Description @Description **Notes** @Description - Deployment is denied if a lab with the target name already exists. @Description - The `images` and `licenses` fields map node kind to image or license path (e.g., {"nokia_srlinux":"ghcr.io/..."}). @Description - When `deploy=true`, the topology is saved to the user's managed lab directory and `outputFile` is ignored. @Description - When `deploy=false` and `outputFile` is empty, YAML is returned in the response. @Description - When `deploy=false` and `outputFile` is set, the file is saved to that path on the server (requires API server write permissions). @Tags Topology Generation @Security BearerAuth @Accept json @Produce json @Param generate_request body models.GenerateRequest true "Topology generation parameters. The 'images' field maps kind to image path." example(`{"name": "3-tier-clos", "tiers": [{"count": 4, "kind": "nokia_srlinux", "type": "ixrd3"}, {"count": 2, "kind": "arista_ceos"}], "defaultKind": "nokia_srlinux", "images": {"nokia_srlinux": "ghcr.io/nokia/srlinux:latest", "arista_ceos": "ceos:4.28.0F", "cisco_xr": "cisco/xrd:7.8.2"}, "licenses": {"nokia_srlinux": "/path/to/license.key"}, "nodePrefix": "clos-node", "groupPrefix": "clos-tier", "managementNetwork": "clos-mgmt", "ipv4Subnet": "172.50.20.0/24", "ipv6Subnet": "2001:172:20:20::/64", "deploy": true, "maxWorkers": 0, "outputFile": ""}`) @Success 200 {object} models.GenerateResponse "Generation successful (YAML or deploy output)" @Failure 400 {object} models.ErrorResponse "Invalid input parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 409 {object} models.ErrorResponse "Conflict (Lab already exists and Deploy=true)" @Failure 500 {object} models.ErrorResponse "Internal server error or clab execution failed" @Router /api/v1/generate [post]

func GetCaptureManager ¶ added in v0.3.0

func GetCaptureManager() *capture.Manager

func GetClabService ¶ added in v0.2.0

func GetClabService() *clab.Service

GetClabService returns the containerlab service instance.

func GetCustomNodesHandler ¶ added in v0.3.0

func GetCustomNodesHandler(c *gin.Context)

@Summary List custom node templates @Description Returns the authenticated user's persisted TopoViewer custom node templates. If none have been saved yet, seeded defaults matching VS Code are returned. @Tags UI @Security BearerAuth @Produce json @Success 200 {object} models.CustomNodesResponse "Custom node templates" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/custom-nodes [get]

func GetEdgeSharkStatusHandler ¶ added in v0.3.0

func GetEdgeSharkStatusHandler(c *gin.Context)

GetEdgeSharkStatusHandler returns current edgeshark availability. @Summary Get EdgeShark status @Description Returns whether EdgeShark is reachable and its runtime details. @Tags Capture @Security BearerAuth @Produce json @Success 200 {object} models.EdgeSharkStatusResponse "EdgeShark status" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/edgeshark/status [get]

func GetNodeBrowserPortsHandler ¶ added in v0.3.0

func GetNodeBrowserPortsHandler(c *gin.Context)

@Summary Get node browser ports @Description Returns exposed host ports for a node suitable for opening in a browser. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.NodeBrowserPortsResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/browser-ports [get]

func GetNodeLogsHandler ¶ added in v0.1.10

func GetNodeLogsHandler(c *gin.Context)

@Summary Get node logs @Description Returns logs for a lab node. @Description @Description **Notes** @Description - When `follow=true`, the response streams as NDJSON (one JSON object per line) until the client disconnects or the 30-minute timeout. @Tags Logs @Security BearerAuth @Produce json,application/x-ndjson @Param labName path string true "Name of the lab" example="my-lab" @Param nodeName path string true "Full name of the container (node)" example="clab-my-lab-srl1" @Param tail query string false "Number of lines to show from the end of logs (default all). Use an integer or 'all'." example="100" default(all) @Param follow query boolean false "Follow log output (stream logs as NDJSON). Note: In Swagger UI, streaming may not display correctly." example="false" @Success 200 {object} models.LogsResponse "Container logs (follow=false). When follow=true, response is NDJSON stream of LogLine objects." @Failure 400 {object} models.ErrorResponse "Invalid input (lab name, node filter, etc.)" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (not owner of the lab)" @Failure 404 {object} models.ErrorResponse "Lab or node not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/nodes/{nodeName}/logs [get]

func GetRunningLabAnnotationsHandler ¶ added in v0.3.0

func GetRunningLabAnnotationsHandler(c *gin.Context)

@Summary Get lab annotations @Description Returns annotations for the specified lab. For deployed labs, the running annotations path is preferred and local files are used as fallback. @Tags Labs @Security BearerAuth @Produce plain @Param labName path string true "Lab name" @Success 200 {string} string "Annotations content" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "File not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/annotations [get] GetRunningLabAnnotationsHandler returns the annotations JSON associated with a lab.

func GetRunningLabYamlHandler ¶ added in v0.3.0

func GetRunningLabYamlHandler(c *gin.Context)

@Summary Get lab topology YAML @Description Returns the topology YAML for the specified lab. For deployed labs, the running topology source path is preferred and local files are used as fallback. @Tags Labs @Security BearerAuth @Produce plain @Param labName path string true "Lab name" @Success 200 {string} string "Topology YAML content" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "File not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/yaml [get] GetRunningLabYamlHandler returns the source YAML used by a lab.

func GetTerminalSessionHandler ¶ added in v0.3.0

func GetTerminalSessionHandler(c *gin.Context)

GetTerminalSessionHandler returns metadata for a terminal session. @Summary Get terminal session @Description Returns metadata and lifecycle state for a terminal session. @Tags Terminal Sessions @Security BearerAuth @Produce json @Param sessionId path string true "Terminal session ID" @Success 200 {object} models.TerminalSessionInfo "Terminal session metadata" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/terminal-sessions/{sessionId} [get]

func GetTopologyFileHandler ¶ added in v0.3.0

func GetTopologyFileHandler(c *gin.Context)

@Summary Read lab topology file @Description Reads a file from within the specified lab directory using a scoped relative path. @Tags Labs @Security BearerAuth @Produce plain @Param labName path string true "Lab name" @Param path query string true "Relative file path inside lab directory" @Success 200 {string} string "File content" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "File not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/file [get]

func GetUserDetailsHandler ¶ added in v0.1.4

func GetUserDetailsHandler(c *gin.Context)

@Summary Get user details @Description Returns details for a specific user. Requires superuser privileges or the user's own account. @Tags Users @Security BearerAuth @Produce json @Param username path string true "Username to get details for" example="john" @Success 200 {object} models.UserDetails "User details" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (Not superuser or not the user's own account)" @Failure 404 {object} models.ErrorResponse "User not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users/{username} [get]

func GetVersionHandler ¶

func GetVersionHandler(c *gin.Context)

@Summary Get containerlab version @Description Returns version information for the containerlab library in use. @Tags Version @Security BearerAuth @Produce json @Success 200 {object} models.VersionResponse "Containerlab version details" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/version [get]

func GetWiresharkVncSessionReadyHandler ¶ added in v0.3.0

func GetWiresharkVncSessionReadyHandler(c *gin.Context)

GetWiresharkVncSessionReadyHandler checks if a wireshark VNC session is reachable. @Summary Get Wireshark VNC session readiness @Description Returns whether a capture VNC session is ready and its proxied URL path. @Tags Capture @Security BearerAuth @Produce json @Param sessionId path string true "Capture session ID" @Success 200 {object} models.CaptureWiresharkVncReadyResponse "Readiness state" @Failure 400 {object} models.ErrorResponse "Invalid request" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/capture/wireshark-vnc-sessions/{sessionId}/ready [get]

func GetWorkspaceFileHandler ¶ added in v0.3.4

func GetWorkspaceFileHandler(c *gin.Context)

@Summary Read lab workspace file @Description Reads a text or binary file from the authenticated user's editable lab workspace root. @Tags Labs @Security BearerAuth @Produce plain @Param path query string true "Relative file path inside the workspace root" @Success 200 {string} string "File content" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "File not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/file [get]

func HeadTopologyFileHandler ¶ added in v0.3.0

func HeadTopologyFileHandler(c *gin.Context)

@Summary Check lab topology file existence @Description Checks whether a file exists inside the specified lab directory. @Tags Labs @Security BearerAuth @Param labName path string true "Lab name" @Param path query string true "Relative file path inside lab directory" @Success 200 "File exists" @Failure 400 "Invalid path" @Failure 401 "Unauthorized" @Failure 404 "File not found" @Failure 500 "Internal server error" @Router /api/v1/labs/{labName}/topology/file [head]

func HealthCheckHandler ¶ added in v0.1.4

func HealthCheckHandler(c *gin.Context)

@Summary Get API server health @Description Returns basic health status for the API server. @Tags Health @Produce json @Success 200 {object} models.HealthResponse "Basic health information" @Router /health [get]

func ImportTopologyFromURLHandler ¶ added in v0.3.0

func ImportTopologyFromURLHandler(c *gin.Context)

@Summary Import topology repository as undeployed lab @Description Clones a supported Git repository URL and registers it as an undeployed lab. @Tags Labs @Security BearerAuth @Accept json @Produce json @Param import_request body models.ImportTopologyFromURLRequest true "Topology source URL" @Param labNameOverride query string false "Override imported lab name" @Success 200 {object} models.ImportTopologyFromURLResponse "Import result" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 409 {object} models.ErrorResponse "Lab already exists" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/topology/import-from-url [post]

func InitCaptureManager ¶ added in v0.3.0

func InitCaptureManager()

func InitHealth ¶ added in v0.1.4

func InitHealth(version string)

InitHealth sets the server start time for uptime tracking and stores the version

func InitSSHManager ¶ added in v0.1.4

func InitSSHManager()

InitSSHManager initializes the SSH manager

func InitTerminalManager ¶ added in v0.3.0

func InitTerminalManager()

func InspectInterfacesHandler ¶

func InspectInterfacesHandler(c *gin.Context)

@Summary List lab interfaces @Description Returns interface details for nodes in a lab. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Name of the lab" @Param node query string false "Filter interfaces for a specific node" @Success 200 {object} models.ClabInspectInterfacesOutput "Interface details" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/interfaces [get]

func InspectLabHandler ¶

func InspectLabHandler(c *gin.Context)

@Summary Inspect lab @Description Returns details for a specific running lab. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Name of the lab to inspect" @Success 200 {object} []models.ClabContainerInfo "Lab containers" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName} [get]

func InstallEdgeSharkHandler ¶ added in v0.3.0

func InstallEdgeSharkHandler(c *gin.Context)

InstallEdgeSharkHandler installs edgeshark using compose. @Summary Install EdgeShark @Description Installs and starts EdgeShark services on the host runtime using compose. @Tags Capture @Security BearerAuth @Produce json @Success 200 {object} models.GenericSuccessResponse "EdgeShark installed" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Superuser privileges required" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/edgeshark/install [post]

func LabGoTTYShareHandler ¶ added in v0.3.0

func LabGoTTYShareHandler(c *gin.Context)

@Summary GoTTY share action @Description Executes GoTTY share action (attach, detach, reattach) for a lab. @Tags Labs - Sharing @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param action path string true "Action (attach|detach|reattach)" @Param port query int false "GoTTY port (attach/reattach only)" @Success 200 {object} models.ShareToolResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/gotty/{action} [post]

func LabSSHXShareHandler ¶ added in v0.3.0

func LabSSHXShareHandler(c *gin.Context)

@Summary SSHX share action @Description Executes SSHX share action (attach, detach, reattach) for a lab. @Tags Labs - Sharing @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param action path string true "Action (attach|detach|reattach)" @Success 200 {object} models.ShareToolResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/sshx/{action} [post]

func ListGlobalIconsHandler ¶ added in v0.3.0

func ListGlobalIconsHandler(c *gin.Context)

@Summary List global custom icons @Description Returns the authenticated user's global custom TopoViewer icon library from ~/.clab/icons. @Tags UI @Security BearerAuth @Produce json @Success 200 {object} models.IconListResponse "Global custom icons" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/icons [get]

func ListLabIconsHandler ¶ added in v0.3.0

func ListLabIconsHandler(c *gin.Context)

@Summary List lab custom icons @Description Returns the custom TopoViewer icons available for a lab, merging lab-local .clab-icons with the global ~/.clab/icons library. Lab-local icons take precedence. @Tags UI @Security BearerAuth @Produce json @Param labName path string true "Lab name" @Success 200 {object} models.IconListResponse "Merged lab icon list" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/ui/icons [get]

func ListLabsHandler ¶

func ListLabsHandler(c *gin.Context)

@Summary List labs @Description Returns details for all running labs. @Description @Description **Notes** @Description - Results are filtered by owner unless the caller is a superuser. @Tags Labs @Security BearerAuth @Produce json @Success 200 {object} models.ClabInspectOutput "All labs" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs [get]

func ListRuntimeImagesHandler ¶ added in v0.3.0

func ListRuntimeImagesHandler(c *gin.Context)

@Summary List runtime images @Tags Images @Security BearerAuth @Produce json @Success 200 {object} models.RuntimeImagesResponse @Failure 401 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/images [get]

func ListSSHSessionsHandler ¶ added in v0.1.4

func ListSSHSessionsHandler(c *gin.Context)

@Summary List SSH sessions @Description Returns active SSH sessions. @Description @Description **Notes** @Description - Regular users see only their sessions. @Description - Superusers can include all sessions via the `all` query parameter. @Tags SSH Access @Security BearerAuth @Produce json @Param all query boolean false "If true and user is superuser, shows sessions for all users (default: false)" example="true" @Success 200 {array} models.SSHSessionInfo "List of active SSH sessions" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (non-superuser attempting to list all sessions)" @Router /api/v1/ssh/sessions [get]

func ListTopologiesHandler ¶ added in v0.3.0

func ListTopologiesHandler(c *gin.Context)

@Summary List editable lab topology files @Description Returns editable topology entries from the authenticated user's lab directory. @Tags Labs @Security BearerAuth @Produce json @Success 200 {array} models.TopologyEntry "Topology entries" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/topology/files [get] ListTopologiesHandler returns editable topology files for the authenticated user.

func ListUsersHandler ¶ added in v0.1.4

func ListUsersHandler(c *gin.Context)

@Summary List users @Description Returns a list of system users. Requires superuser privileges. @Tags Users @Security BearerAuth @Produce json @Success 200 {array} models.UserDetails "List of user details" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users [get]

func ListWorkspaceTreeHandler ¶ added in v0.3.4

func ListWorkspaceTreeHandler(c *gin.Context)

@Summary List lab workspace files @Description Lists files and folders inside the authenticated user's editable lab workspace root. @Tags Labs @Security BearerAuth @Produce json @Param path query string false "Relative directory path inside the workspace root" @Success 200 {array} models.WorkspaceFileEntry "Workspace entries" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Directory not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/tree [get]

func LoginHandler ¶

func LoginHandler(c *gin.Context)

LoginHandler - Handles user authentication @Summary Log in @Description Authenticates a user and returns a JWT token. @Tags Auth @Accept json @Produce json @Param credentials body models.LoginRequest true "User Credentials" @Success 200 {object} models.LoginResponse "JWT token" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Invalid credentials" @Failure 500 {object} models.ErrorResponse "Internal server error (PAM config?)" @Router /login [post]

func PauseNodeHandler ¶ added in v0.3.0

func PauseNodeHandler(c *gin.Context)

@Summary Pause node @Description Pauses a running node in a lab. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/pause [post]

func ProxyWiresharkVncSessionHandler ¶ added in v0.3.0

func ProxyWiresharkVncSessionHandler(c *gin.Context)

ProxyWiresharkVncSessionHandler proxies noVNC assets and websocket traffic. @Summary Proxy Wireshark VNC assets @Description Proxies noVNC HTTP assets for a capture session. WebSocket upgrades on this path are used by noVNC but are not represented in Swagger. @Tags Capture @Security BearerAuth @Produce html @Param sessionId path string true "Capture session ID" @Param proxyPath path string true "Proxy subpath under the noVNC root" @Success 200 {string} string "Proxied noVNC asset response" @Failure 400 {object} models.ErrorResponse "Invalid request" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Failure 502 {object} models.ErrorResponse "VNC proxy upstream error" @Router /api/v1/capture/wireshark-vnc-sessions/{sessionId}/vnc/{proxyPath} [get]

func PullRuntimeImageHandler ¶ added in v0.3.0

func PullRuntimeImageHandler(c *gin.Context)

@Summary Pull a runtime image @Tags Images @Security BearerAuth @Accept json @Produce json @Param request body models.RuntimeImagePullRequest true "Image reference" @Success 200 {object} models.RuntimeImageActionResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/images/pull [post]

func PutCustomNodesHandler ¶ added in v0.3.0

func PutCustomNodesHandler(c *gin.Context)

@Summary Replace custom node templates @Description Replaces the authenticated user's full TopoViewer custom node template collection. @Tags UI @Security BearerAuth @Accept json @Produce json @Param request body models.CustomNodesReplaceRequest true "Replacement custom node template collection" @Success 200 {object} models.CustomNodesResponse "Updated custom node templates" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/custom-nodes [put]

func PutRunningLabAnnotationsHandler ¶ added in v0.3.0

func PutRunningLabAnnotationsHandler(c *gin.Context)

@Summary Update lab annotations @Description Updates annotations for the specified lab. For deployed labs, writes to the running annotations path when present and otherwise writes to local files. @Tags Labs @Security BearerAuth @Accept plain @Produce json @Param labName path string true "Lab name" @Param content body string true "Annotations content" @Success 200 {object} models.SimpleSuccessResponse "Write success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/annotations [put] PutRunningLabAnnotationsHandler updates or creates the annotations JSON associated with a lab.

func PutRunningLabYamlHandler ¶ added in v0.3.0

func PutRunningLabYamlHandler(c *gin.Context)

@Summary Update lab topology YAML @Description Updates the topology YAML for the specified lab. For deployed labs, writes to the running topology source when present and otherwise writes to local files. @Tags Labs @Security BearerAuth @Accept plain @Produce json @Param labName path string true "Lab name" @Param content body string true "Topology YAML content" @Success 200 {object} models.SimpleSuccessResponse "Write success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/yaml [put] PutRunningLabYamlHandler updates the source YAML used by a lab.

func PutTopologyFileHandler ¶ added in v0.3.0

func PutTopologyFileHandler(c *gin.Context)

@Summary Write lab topology file @Description Writes a file inside the specified lab directory using a scoped relative path. @Tags Labs @Security BearerAuth @Accept plain @Produce json @Param labName path string true "Lab name" @Param path query string true "Relative file path inside lab directory" @Param content body string true "File content" @Success 200 {object} models.SimpleSuccessResponse "Write success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/file [put]

func PutWorkspaceFileHandler ¶ added in v0.3.4

func PutWorkspaceFileHandler(c *gin.Context)

@Summary Write lab workspace file @Description Writes a file inside the authenticated user's editable lab workspace root. @Tags Labs @Security BearerAuth @Accept plain @Produce json @Param path query string true "Relative file path inside the workspace root" @Param content body string true "File content" @Success 200 {object} models.SimpleSuccessResponse "Write success" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/file [put]

func ReconcileLabIconsHandler ¶ added in v0.3.0

func ReconcileLabIconsHandler(c *gin.Context)

@Summary Reconcile lab custom icons @Description Copies used custom icons from the global ~/.clab/icons library into the lab-local .clab-icons directory and removes unused lab-local custom icons. @Tags UI @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" @Param request body models.IconReconcileRequest true "Used custom icon names" @Success 200 {object} models.SimpleSuccessResponse "Reconcile success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/ui/icons/reconcile [post]

func RedeployLabHandler ¶

func RedeployLabHandler(c *gin.Context)

@Summary Redeploy lab @Description Redeploys a lab by name. @Description @Description **Notes** @Description - This operation destroys the lab and then deploys it again. @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Name of the lab to redeploy" @Param cleanup query boolean false "Remove containerlab lab artifacts during destroy phase" @Param graceful query boolean false "Attempt graceful shutdown" @Param gracefulTimeout query string false "Override graceful shutdown timeout when graceful=true (for example 5s or 2m)" @Param keepMgmtNet query boolean false "Keep the management network" @Param maxWorkers query int false "Limit concurrent workers" @Param exportTemplate query string false "Custom Go template file for topology data export" @Param skipPostDeploy query boolean false "Skip post-deploy actions" @Param skipLabdirAcl query boolean false "Skip setting extended ACLs on lab directory" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.ClabInspectOutput "Redeployed lab details" @Failure 400 {object} models.ErrorResponse "Invalid lab name" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName} [put]

func RemoveRuntimeImageHandler ¶ added in v0.3.0

func RemoveRuntimeImageHandler(c *gin.Context)

@Summary Remove a runtime image @Tags Images @Security BearerAuth @Produce json @Param reference query string true "Image reference or ID" @Param force query bool false "Force image removal" @Success 200 {object} models.RuntimeImageActionResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 403 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/images [delete]

func RenameTopologyFileHandler ¶ added in v0.3.0

func RenameTopologyFileHandler(c *gin.Context)

@Summary Rename lab topology file @Description Renames or moves a file inside the specified lab directory using scoped relative paths. @Tags Labs @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" @Param rename_request body models.TopologyFileRenameRequest true "Old and new relative file paths" @Success 200 {object} models.SimpleSuccessResponse "Rename success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/file/rename [post]

func RenameWorkspaceFileHandler ¶ added in v0.3.4

func RenameWorkspaceFileHandler(c *gin.Context)

@Summary Rename lab workspace file @Description Renames or moves a file inside the authenticated user's editable lab workspace root. @Tags Labs @Security BearerAuth @Accept json @Produce json @Param rename_request body models.WorkspaceFileRenameRequest true "Old and new relative file paths" @Success 200 {object} models.SimpleSuccessResponse "Rename success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/file/rename [post]

func RequestSSHAccessHandler ¶ added in v0.1.4

func RequestSSHAccessHandler(c *gin.Context)

@Summary Request temporary SSH access details @Description Creates temporary SSH access to a lab node and returns connection details for an external SSH client. @Description This endpoint does not create a browser terminal session. For browser terminals, use `/api/v1/labs/{labName}/nodes/{nodeName}/terminal-sessions` with `protocol=ssh`. @Tags SSH Access @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" example="my-lab" @Param nodeName path string true "Full container name of the node (e.g., clab-my-lab-srl1)" example="clab-my-lab-srl1" @Param sshRequest body models.SSHAccessRequest false "SSH access parameters" @Success 200 {object} models.SSHAccessResponse "SSH connection details" @Failure 400 {object} models.ErrorResponse "Invalid request parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (not owner of the lab)" @Failure 404 {object} models.ErrorResponse "Lab or node not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/nodes/{nodeName}/ssh [post]

func RequestTerminalSessionHandler ¶ added in v0.3.0

func RequestTerminalSessionHandler(c *gin.Context)

RequestTerminalSessionHandler creates a constrained interactive terminal session for an owned node. @Summary Create browser terminal session @Description Creates a constrained interactive terminal session for an owned lab node using one of the supported protocols: `ssh`, `shell`, or `telnet`. @Description @Description **Protocol behavior** @Description - `ssh`: launches the server-side `ssh` client in a PTY directly to the node management IP and streams that terminal over WebSocket. @Description - `shell`: launches a PTY-backed `docker|podman exec -it <container> <server-selected-command>` session. @Description - `telnet`: launches a PTY-backed `docker|podman exec -it <container> telnet 127.0.0.1 <port>` session. @Description @Description **Security notes** @Description - The backend chooses the launch command for every protocol. Clients choose only the protocol and terminal size. @Description - Access is limited to owned nodes unless the caller is a configured superuser. @Description @Description **Relationship to `/api/v1/labs/{labName}/nodes/{nodeName}/ssh`** @Description - This endpoint creates the interactive browser terminal session. @Description - The separate `/ssh` endpoint returns temporary SSH access details for an external SSH client and is not required for browser terminals. @Tags Terminal Sessions @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab name" example="my-lab" @Param nodeName path string true "Full container name of the node (e.g., clab-my-lab-srl1)" example="clab-my-lab-srl1" @Param terminal_request body models.TerminalSessionRequest true "Terminal session creation parameters" @Success 200 {object} models.TerminalSessionInfo "Created terminal session" @Failure 400 {object} models.ErrorResponse "Invalid request parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab or node not found" @Failure 429 {object} models.ErrorResponse "Too many active terminal sessions" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/nodes/{nodeName}/terminal-sessions [post]

func ResetNetemHandler ¶

func ResetNetemHandler(c *gin.Context)

@Summary Reset link impairments (netem) @Description Resets (removes) netem impairments from a specific interface of a containerlab node owned by the authenticated user. Superusers may operate on any node. @Tags Tools - Netem @Security BearerAuth @Accept json @Produce json @Param netem_reset_request body models.NetemResetRequest true "Netem Reset Parameters" @Success 200 {object} models.GenericSuccessResponse "Impairments reset successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 404 {object} models.ErrorResponse "Container or interface not found, or container not owned by user" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/netem/reset [post]

func RestartLabNodesHandler ¶ added in v0.3.0

func RestartLabNodesHandler(c *gin.Context)

@Summary Restart lab nodes @Description Restarts all nodes in a deployed lab while preserving containerlab dataplane links. @Description @Description **Notes** @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/restart [post]

func RestartNodeHandler ¶ added in v0.3.0

func RestartNodeHandler(c *gin.Context)

@Summary Restart node @Description Restarts a node in a lab while preserving containerlab dataplane links. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/restart [post]

func RunLabFcliHandler ¶ added in v0.3.0

func RunLabFcliHandler(c *gin.Context)

@Summary Run fcli command @Description Runs an fcli command against the selected lab topology. @Tags Labs - Tools @Security BearerAuth @Accept json @Produce json @Param labName path string true "Lab Name" @Param fcli_request body models.FcliCommandRequest true "fcli command request" @Success 200 {object} models.FcliCommandResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/fcli [post]

func SaveCustomNodeHandler ¶ added in v0.3.0

func SaveCustomNodeHandler(c *gin.Context)

@Summary Save custom node template @Description Creates or updates a single TopoViewer custom node template for the authenticated user. @Tags UI @Security BearerAuth @Accept json @Produce json @Param request body models.CustomNodeTemplate true "Custom node template payload" @Success 200 {object} models.CustomNodesResponse "Updated custom node templates" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/custom-nodes [post]

func SaveLabConfigHandler ¶

func SaveLabConfigHandler(c *gin.Context)

@Summary Save lab configuration @Description Saves the running configuration for nodes in a lab. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Name of the lab" @Param nodeFilter query string false "Save config only for specific nodes" @Success 200 {object} models.SaveConfigResponse "Configuration saved" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Lab not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/save [post]

func SetClabService ¶ added in v0.2.0

func SetClabService(svc *clab.Service)

SetClabService sets the containerlab service instance for use by handlers.

func SetDefaultCustomNodeHandler ¶ added in v0.3.0

func SetDefaultCustomNodeHandler(c *gin.Context)

@Summary Set default custom node template @Description Sets the default TopoViewer custom node template for the authenticated user. @Tags UI @Security BearerAuth @Accept json @Produce json @Param request body models.CustomNodeDefaultRequest true "Default custom node selection" @Success 200 {object} models.CustomNodesResponse "Updated custom node templates" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Custom node not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/custom-nodes/default [post]

func SetNetemHandler ¶

func SetNetemHandler(c *gin.Context)

@Summary Set link impairments (netem) @Description Sets netem impairments (delay, jitter, loss, rate limiting, corruption) on a specific interface of a containerlab node owned by the authenticated user. Superusers may operate on any node. @Tags Tools - Netem @Security BearerAuth @Accept json @Produce json @Param netem_set_request body models.NetemSetRequest true "Netem Set Parameters" @Success 200 {object} models.GenericSuccessResponse "Impairments set successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 404 {object} models.ErrorResponse "Container or interface not found, or container not owned by user" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/netem/set [post]

func SetupRoutes ¶

func SetupRoutes(router *gin.Engine)

SetupRoutes defines all the API endpoints and applies middleware.

func ShowNetemHandler ¶

func ShowNetemHandler(c *gin.Context)

@Summary Show link impairments (netem) @Description Lists netem impairments for a containerlab node owned by the authenticated user. Superusers may inspect any node. @Tags Tools - Netem @Security BearerAuth @Produce json @Param containerName query string true "Container/node name" @Success 200 {object} models.NetemShowResponse "Netem impairments" @Failure 400 {object} models.ErrorResponse "Invalid input parameters" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 404 {object} models.ErrorResponse "Container not found, or container not owned by user" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/netem/show [get]

func ShutdownCaptureManager ¶ added in v0.3.0

func ShutdownCaptureManager()

func ShutdownSSHManager ¶ added in v0.1.4

func ShutdownSSHManager()

ShutdownSSHManager gracefully shuts down the SSH manager

func ShutdownTerminalManager ¶ added in v0.3.0

func ShutdownTerminalManager()

func SignCertHandler ¶

func SignCertHandler(c *gin.Context)

@Summary Sign certificate @Description Creates a certificate/key and signs it with a previously generated CA. Requires superuser privileges. @Description @Description **Notes** @Description - Files are stored in the user's `~/.clab/certs/<ca_name>/` directory. @Tags Tools - Certificates @Security BearerAuth @Accept json @Produce json @Param sign_request body models.CertSignRequest true "Certificate Signing Parameters" @Success 200 {object} models.CertResponse "Certificate signed successfully" @Failure 400 {object} models.ErrorResponse "Invalid input parameters (name, hosts, CA name, etc.)" @Failure 401 {object} models.ErrorResponse "Unauthorized (JWT)" @Failure 403 {object} models.ErrorResponse "Forbidden (User is not a superuser)" @Failure 404 {object} models.ErrorResponse "Specified CA not found" @Failure 500 {object} models.ErrorResponse "Internal server error (filesystem, clab execution)" @Router /api/v1/tools/certs/sign [post]

func StartLabNodesHandler ¶ added in v0.3.0

func StartLabNodesHandler(c *gin.Context)

@Summary Start lab nodes @Description Starts all nodes in a deployed lab while preserving containerlab dataplane links. @Description @Description **Notes** @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/start [post]

func StartNodeHandler ¶ added in v0.3.0

func StartNodeHandler(c *gin.Context)

@Summary Start node @Description Starts a stopped node in a lab. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/start [post]

func StopLabNodesHandler ¶ added in v0.3.0

func StopLabNodesHandler(c *gin.Context)

@Summary Stop lab nodes @Description Stops all nodes in a deployed lab while preserving containerlab dataplane links. @Description @Description **Notes** @Description - `stream=true` returns `application/x-ndjson` lifecycle events. @Description - `includeLogs=true` includes captured lifecycle logs in the JSON response. @Tags Labs @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param stream query boolean false "Stream lifecycle output as NDJSON events" @Param includeLogs query boolean false "Include captured lifecycle logs in the JSON response" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/stop [post]

func StopNodeHandler ¶ added in v0.3.0

func StopNodeHandler(c *gin.Context)

@Summary Stop node @Description Stops a running node in a lab. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/stop [post]

func StreamEventsHandler ¶ added in v0.2.0

func StreamEventsHandler(c *gin.Context)

@Summary Stream containerlab events @Description Streams containerlab events in real time as NDJSON (one JSON object per line). @Description @Description **Notes** @Description - The response stays open until the client disconnects. @Description @Description **Examples** @Description NDJSON (one JSON object per line): @Description ```json @Description {"time":1706918400,"type":"container","action":"start","attributes":{"name":"clab-mylab-srl1","lab":"mylab","clab-node-name":"srl1","clab-node-kind":"nokia_srlinux"}} @Description {"time":1706918405,"type":"container","action":"start","attributes":{"name":"clab-mylab-srl2","lab":"mylab","clab-node-name":"srl2","clab-node-kind":"nokia_srlinux"}} @Description ``` @Description @Description @Description Interface stats (interfaceStats=true): @Description ```json @Description {"time":1706918410,"type":"interface-stats","action":"stats","attributes":{"name":"clab-mylab-srl1","lab":"mylab","interface":"e1-1","rx_bytes":123456,"tx_bytes":654321}} @Description ``` @Tags Events @Security BearerAuth @Produce application/x-ndjson @Param initialState query boolean false "Include initial snapshot events when the stream starts." default(false) @Param interfaceStats query boolean false "Include interface stats events." default(false) @Param interfaceStatsInterval query string false "Interval for interface stats collection (e.g., 10s). Requires interfaceStats=true." default(10s) @Success 200 {object} models.EventResponse "Event stream - NDJSON (one JSON object per line)" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/events [get]

func StreamTerminalSessionHandler ¶ added in v0.3.0

func StreamTerminalSessionHandler(c *gin.Context)

StreamTerminalSessionHandler upgrades the request to a WebSocket stream for terminal I/O. @Summary Stream terminal session @Description Upgrades the request to a WebSocket connection for terminal input, output, resize, and close events. @Description @Description **Protocol notes** @Description - Connect with a WebSocket client to this endpoint after creating a terminal session. @Description - Client messages are JSON objects with `type` set to `input`, `resize`, or `close`. @Description - Server messages are JSON objects with `type` set to `ready`, `output`, or `exit`. @Tags Terminal Sessions @Security BearerAuth @Produce json @Param sessionId path string true "Terminal session ID" @Success 101 {string} string "Switching Protocols to WebSocket" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 409 {object} models.ErrorResponse "Session already attached" @Failure 410 {object} models.ErrorResponse "Session already exited" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/terminal-sessions/{sessionId}/stream [get]

func StreamTopologyFileEventsHandler ¶ added in v0.3.0

func StreamTopologyFileEventsHandler(c *gin.Context)

@Summary Stream topology document events @Description Streams topology YAML/annotations change events for a single lab topology document pair as NDJSON. @Tags Labs @Security BearerAuth @Produce application/x-ndjson @Param labName path string true "Lab name" @Param path query string true "Relative topology YAML or annotations path inside lab directory" @Success 200 {object} models.TopologyDocEventResponse "Topology document event stream" @Failure 400 {object} models.ErrorResponse "Invalid path" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/{labName}/topology/events [get]

func StreamWorkspaceEventsHandler ¶ added in v0.3.4

func StreamWorkspaceEventsHandler(c *gin.Context)

@Summary Stream lab workspace file events @Description Streams create/change/delete/rename events inside the authenticated user's editable lab workspace root as NDJSON. @Tags Labs @Security BearerAuth @Produce application/x-ndjson @Success 200 {object} models.WorkspaceFileEventResponse "Workspace file event stream" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/labs/workspace/events [get]

func SystemMetricsHandler ¶ added in v0.1.4

func SystemMetricsHandler(c *gin.Context)

@Summary Get system metrics @Description Returns detailed CPU, memory, and disk metrics for the API server. Requires authentication. @Tags Health @Security BearerAuth @Produce json @Success 200 {object} models.MetricsResponse "System metrics" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 500 {object} models.ErrorResponse "Internal server error gathering metrics" @Router /api/v1/health/metrics [get]

func TerminateSSHSessionHandler ¶ added in v0.1.4

func TerminateSSHSessionHandler(c *gin.Context)

@Summary Terminate SSH session @Description Terminates a specific SSH session by port. @Tags SSH Access @Security BearerAuth @Produce json @Param port path int true "SSH session port to terminate" example="2223" @Success 200 {object} models.GenericSuccessResponse "Session terminated successfully" @Failure 400 {object} models.ErrorResponse "Invalid port parameter" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (not owner of the session)" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ssh/sessions/{port} [delete]

func TerminateTerminalSessionHandler ¶ added in v0.3.0

func TerminateTerminalSessionHandler(c *gin.Context)

TerminateTerminalSessionHandler closes a terminal session. @Summary Terminate terminal session @Description Terminates a terminal session owned by the caller (or any session for a superuser). @Tags Terminal Sessions @Security BearerAuth @Produce json @Param sessionId path string true "Terminal session ID" @Success 200 {object} models.GenericSuccessResponse "Terminal session terminated" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 404 {object} models.ErrorResponse "Session not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/terminal-sessions/{sessionId} [delete]

func UninstallEdgeSharkHandler ¶ added in v0.3.0

func UninstallEdgeSharkHandler(c *gin.Context)

UninstallEdgeSharkHandler removes edgeshark compose services. @Summary Uninstall EdgeShark @Description Stops and removes EdgeShark services managed by compose. @Tags Capture @Security BearerAuth @Produce json @Success 200 {object} models.GenericSuccessResponse "EdgeShark uninstalled" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Superuser privileges required" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/tools/edgeshark/uninstall [post]

func UnpauseNodeHandler ¶ added in v0.3.0

func UnpauseNodeHandler(c *gin.Context)

@Summary Unpause node @Description Unpauses a paused node in a lab. @Tags Labs - Nodes @Security BearerAuth @Produce json @Param labName path string true "Lab Name" @Param nodeName path string true "Node Name" @Success 200 {object} models.GenericSuccessResponse @Failure 400 {object} models.ErrorResponse @Failure 401 {object} models.ErrorResponse @Failure 404 {object} models.ErrorResponse @Failure 500 {object} models.ErrorResponse @Router /api/v1/labs/{labName}/nodes/{nodeName}/unpause [post]

func UpdateUserHandler ¶ added in v0.1.4

func UpdateUserHandler(c *gin.Context)

@Summary Update user @Description Updates an existing user. Regular users may update only their own profile fields. Group and superuser status changes require superuser privileges. @Tags Users @Security BearerAuth @Accept json @Produce json @Param username path string true "Username to update" example="john" @Param user body models.UserUpdateRequest true "User details to update" @Success 200 {object} models.GenericSuccessResponse "User updated successfully" @Failure 400 {object} models.ErrorResponse "Invalid request body" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 403 {object} models.ErrorResponse "Forbidden (Not superuser or not the user's own account)" @Failure 404 {object} models.ErrorResponse "User not found" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/users/{username} [put] internal/api/user_handlers.go - Fix for UpdateUserHandler

func UploadGlobalIconHandler ¶ added in v0.3.0

func UploadGlobalIconHandler(c *gin.Context)

@Summary Upload global custom icon @Description Uploads a new global custom TopoViewer icon into ~/.clab/icons for the authenticated user. @Tags UI @Security BearerAuth @Accept json @Produce json @Param request body models.IconUploadRequest true "Custom icon upload payload" @Success 200 {object} models.IconUploadResponse "Upload success" @Failure 400 {object} models.ErrorResponse "Invalid input" @Failure 401 {object} models.ErrorResponse "Unauthorized" @Failure 409 {object} models.ErrorResponse "Rejected due to built-in icon name conflict" @Failure 500 {object} models.ErrorResponse "Internal server error" @Router /api/v1/ui/icons [post]

Types ¶

This section is empty.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL