Environment Variable Configuration¶

TL;DR - Prefer interactive auth with --interactive-auth for ad‑hoc runs - Set NW_USER_DEFAULT and NW_PASSWORD_DEFAULT for shared defaults - Override per device/group with NW_USER_* and NW_PASSWORD_*

This document describes how to set up secure credential management using environment variables for Networka.

Example precedence

1) Run with interactive auth (highest):

nw run router1 system_info --interactive-auth

2) Use device-specific overrides when set (e.g., NW_USER_ROUTER1, NW_PASSWORD_ROUTER1)

3) Fall back to defaults when no overrides exist:

export NW_USER_DEFAULT=admin
export NW_PASSWORD_DEFAULT=secret
nw run router1 system_info

Overview¶

For security best practices, all device credentials should be managed via environment variables rather than YAML files. This prevents sensitive information from being stored in version control.

The Networka now supports multiple levels of credential management:

Device-specific credentials - For individual devices
Group-level credentials - For entire device groups
Default credentials - Fallback for all devices

Required Environment Variables¶

Default Credentials¶

Set these environment variables for the default credentials used by devices that don't have specific overrides:

export NW_USER_DEFAULT=admin
export NW_PASSWORD_DEFAULT=your_secure_password_here

Device-Specific Credentials (Optional)¶

You can override credentials for specific devices using the pattern:

NW_USER_DEVICENAME - Username for the specific device
NW_PASSWORD_DEVICENAME - Password for the specific device

Device names should match those in your configuration and will be automatically converted to uppercase with hyphens replaced by underscores.

Examples:

# For device 'sw-acc1' in config
export NW_USER_SW_ACC1=admin
export NW_PASSWORD_SW_ACC1=switch1_password

# For device 'sw-acc2' in config
export NW_USER_SW_ACC2=admin
export NW_PASSWORD_SW_ACC2=switch2_password

# For device 'sw-dist1' in config
export NW_USER_SW_DIST1=admin
export NW_PASSWORD_SW_DIST1=distribution_password

Group-Level Credentials (New Feature)¶

You can set credentials for entire device groups using the pattern:

NW_USER_GROUPNAME - Username for all devices in the group
NW_PASSWORD_GROUPNAME - Password for all devices in the group

Group names should match those in groups.yml:

# For group 'access_switches' in groups.yml
export NW_USER_ACCESS_SWITCHES=switch_admin
export NW_PASSWORD_ACCESS_SWITCHES=access_layer_password

# For group 'critical_infrastructure' in groups.yml
export NW_USER_CRITICAL_INFRASTRUCTURE=critical_admin
export NW_PASSWORD_CRITICAL_INFRASTRUCTURE=critical_systems_password

Setup Methods¶

Option 1: Environment File (.env) - Recommended¶

The Network Toolkit automatically loads environment variables from .env files, making credential management simple and secure.

Copy the example environment file:

cp .env.example .env

Edit .env with your actual credentials:

nano .env

Run the tool directly - the .env file is loaded automatically:
```
nw run system_info sw-acc1
```

.env File Locations¶

The toolkit automatically looks for .env files in the following order (highest to lowest precedence):

Environment Variables (Highest priority) - Variables already set in your shell
Config Directory - .env file in the same directory as your config files
Current Working Directory (Lowest priority) - .env file in your current directory

This allows for flexible credential management:

Place .env in your project/config directory for project-specific credentials
Place .env in your working directory for global defaults
Use shell environment variables for runtime overrides

Option 2: Export in Shell¶

Add to your ~/.bashrc or ~/.zshrc:

# Network Toolkit Credentials
export NW_USER_DEFAULT=admin
export NW_PASSWORD_DEFAULT=your_secure_password

# Device-specific overrides
export NW_PASSWORD_SW_ACC1=switch1_password
export NW_PASSWORD_SW_ACC2=switch2_password
export NW_PASSWORD_SW_DIST1=distribution_password

Then reload your shell:

source ~/.bashrc

Option 3: Runtime Export¶

Set variables directly before running commands:

export NW_USER_DEFAULT=admin
export NW_PASSWORD_DEFAULT=your_password
python -m network_toolkit.cli run system_info sw-acc1

Security Best Practices¶

Never commit .env files: The .env file is already in .gitignore - keep it that way
Use strong passwords: Generate unique, complex passwords for each device
Limit environment access: Only set these variables in environments where the tool runs
Regular rotation: Change passwords regularly and update environment variables accordingly
Least privilege: Create device-specific users with minimal required permissions

Credential Resolution Order¶

The toolkit resolves credentials in this priority order:

Interactive credentials (Highest) - When --interactive-auth is used
Device configuration - Explicitly set credentials in device YAML files (supported but discouraged)
Device-specific environment variables - NW_USER_DEVICENAME and NW_PASSWORD_DEVICENAME
Group-level credentials - From group configuration or NW_USER_GROUPNAME and NW_PASSWORD_GROUPNAME
Default environment variables (Lowest) - NW_USER_DEFAULT and NW_PASSWORD_DEFAULT

This precedence allows you to:

Set global defaults with NW_USER_DEFAULT and NW_PASSWORD_DEFAULT
Override entire groups with group-level credentials
Override specific devices with device-specific credentials
Override everything with interactive authentication

Troubleshooting¶

"Default username not found in environment"¶

This error means NW_USER_DEFAULT is not set in any of the credential sources. Set it using one of the methods above.

"Default password not found in environment"¶

This error means NW_PASSWORD_DEFAULT is not set in any of the credential sources. Set it using one of the methods above.

Device-specific credentials not working¶

Check that:

The environment variable name matches the device name in your config
Hyphens in device names become underscores in environment variables
Device names are converted to uppercase for environment variables
The variables are exported in your current shell session
Use the new NW_ prefix, not the old NT_ prefix

Group credentials not being applied¶

Check that:

The group name in the environment variable matches exactly the group name in groups.yml
The device is actually a member of the group (check with nw list groups)
Use the correct format: NW_USER_GROUPNAME and NW_PASSWORD_GROUPNAME
Group credentials have lower priority than device-specific credentials

Verification¶

You can verify your environment variables are set correctly:

# Check if default credentials are set
echo "Default user: $NW_USER_DEFAULT"
echo "Default password set: $(if [ -n "$NW_PASSWORD_DEFAULT" ]; then echo "Yes"; else echo "No"; fi)"

# Check device-specific credentials
echo "SW-ACC1 user: $NW_USER_SW_ACC1"
echo "SW-ACC1 password set: $(if [ -n "$NW_PASSWORD_SW_ACC1" ]; then echo "Yes"; else echo "No"; fi)"

# Check group credentials
echo "Access switches user: $NW_USER_ACCESS_SWITCHES"
echo "Access switches password set: $(if [ -n "$NW_PASSWORD_ACCESS_SWITCHES" ]; then echo "Yes"; else echo "No"; fi)"

Migration from Old Configuration¶

If you have an existing legacy single-file config with hardcoded credentials:

Extract all user and password values from the file
Set them as environment variables using the patterns above
Remove or comment out the user and password lines from your config files
Test the configuration to ensure devices can still connect

The updated configuration will automatically fall back to environment variables when device-specific credentials are not found in the YAML file.