1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# Concepts
Key concepts and architecture of PyVyOS.
## Architecture Overview
PyVyOS is built on a REST client architecture:
- `RestClient`: Base class handling HTTP communication
- `VyDevice`: High-level interface for VyOS operations
- `ApiResponse`: Standardized response structure
## API Command Structure
VyOS API uses a hierarchical command structure:
- Commands: `configure`, `retrieve`, `show`, `generate`, `reset`
- Operations: `set`, `delete`, `showConfig`, `returnValues`
- Paths: Array representing configuration hierarchy
## Path Format
Paths are always arrays representing the configuration tree:
```python
# Single path
["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]
# Multiple paths (for configure_set)
[
["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"],
["interfaces", "ethernet", "eth0", "description", "Management"]
]
```
## Response Handling
All methods return `ApiResponse`:
- Consistent error checking
- Sanitized request payloads (API keys removed)
- Structured result data
## Operation Types
### Configuration Operations
- `set`: Add or modify configuration
- `delete`: Remove configuration
- `showConfig`: Get full configuration
- `returnValues`: Get specific values
### Operational Commands
- `show`: Execute show commands
- `generate`: Generate configurations/keys
- `reset`: Reset state/cache
## Multi-Operation Requests
`configure_multiple_op` allows atomic operations:
- Multiple set/delete operations in one API call
- Transaction-like behavior
- Better performance than individual calls
## Error Handling Strategy
PyVyOS uses defensive error handling:
- Network errors captured as exceptions
- API errors returned in response.error
- HTTP status codes in response.status
## Security Considerations
- API keys never appear in response.request
- SSL verification configurable per connection
- Timeout protection prevents hanging connections
## Connection Lifecycle
1. Initialize VyDevice with connection parameters
2. Parameters validated on initialization
3. Each method creates new HTTP request
4. Responses parsed and returned as ApiResponse
## Best Practices
- Use environment variables for credentials
- Enable SSL verification in production
- Handle errors explicitly
- Use configure_multiple_op for bulk changes
- Set appropriate timeouts for operations
|
