0
# Administrative Tools
1

2
Specialized administrative utility functions for Grafana management including alert management, user role management, and permission restoration. These tools provide operational capabilities beyond basic backup and restore functionality.
3

4
## Capabilities
5

6
### Main Tools Interface
7

8
The primary tools entry point that provides access to specialized administrative functions.
9

10
```python { .api }
11
def main(precommand_args, settings):
12
    """
13
    Main tools interface providing access to administrative utilities
14
    
15
    Args:
16
        precommand_args (dict): Arguments from main command line
17
        settings (dict): Configuration settings loaded from grafanaSettings
18
        
19
    Available commands: pause-alerts, unpause-alerts, make-users-viewers, restore-users
20
    """
21
```
22

23
## Alert Management Tools
24

25
### Pause All Alerts
26

27
Temporarily disable all dashboard alerts in the Grafana instance for maintenance or troubleshooting.
28

29
```python { .api }
30
def main(args, settings):
31
    """
32
    Pause all dashboard alerts in Grafana instance
33
    
34
    Module: grafana_backup.pause_alerts
35
    Features: Bulk alert disabling, state preservation, maintenance mode
36
    Safety: Preserves alert configurations while disabling notifications
37
    Output: JSON file with paused alert details for later restoration
38
    """
39
```
40

41
### Unpause Alerts
42

43
Restore previously paused alerts from a saved alert state file.
44

45
```python { .api }
46
def main(args, settings):
47
    """
48
    Unpause alerts from saved alert state file
49
    
50
    Module: grafana_backup.unpause_alerts
51
    Args:
52
        args['<alerts_filename>']: Path to JSON file with paused alert details
53
    Features: Selective alert restoration, state validation, error recovery
54
    Safety: Only restores alerts that were previously paused by pause-alerts
55
    """
56
```
57

58
## User Management Tools
59

60
### Convert Users to Viewers
61

62
Convert all non-admin users to viewer role for security lockdown scenarios.
63

64
```python { .api }
65
def main(args, settings):
66
    """
67
    Convert all users to viewer role except administrators
68
    
69
    Module: grafana_backup.make_users_viewers
70
    Features: Bulk role conversion, admin preservation, reversible operation
71
    Safety: Preserves admin users, creates backup of original user roles
72
    Requires: Basic authentication (admin credentials)
73
    """
74
```
75

76
### Restore User Permissions
77

78
Restore user roles and permissions from a previously saved user state file.
79

80
```python { .api }
81
def main(args, settings):
82
    """
83
    Restore user permissions from saved user state file
84
    
85
    Module: grafana_backup.restore_user_permissions
86
    Args:
87
        args['<users_filename>']: Path to JSON file with user permission details
88
    Features: Role restoration, permission validation, selective restoration
89
    Requires: Basic authentication (admin credentials)
90
    """
91
```
92

93
## Usage Examples  
94

95
### Alert Management Workflow
96

97
```python
98
from grafana_backup.tools import main as tools_main
99
from grafana_backup.grafanaSettings import main as load_config
100

101
# Load configuration
102
settings = load_config('/path/to/grafanaSettings.json')
103

104
# Pause all alerts before maintenance
105
pause_args = {
106
    'tools': True,
107
    'pause-alerts': True,
108
    '--config': None
109
}
110
tools_main(pause_args, settings)
111

112
# ... perform maintenance operations ...
113

114
# Unpause alerts after maintenance
115
unpause_args = {
116
    'tools': True,
117
    'unpause-alerts': True,
118
    '<alerts_filename>': 'paused_alerts_202501011200.json',
119
    '--config': None
120
}
121
tools_main(unpause_args, settings)
122
```
123

124
### User Role Management Workflow
125

126
```python
127
# Convert all users to viewers for security lockdown
128
viewer_args = {
129
    'tools': True,
130
    'make-users-viewers': True,
131
    '--config': None
132
}
133
tools_main(viewer_args, settings)
134

135
# ... security incident response ...
136

137
# Restore original user permissions
138
restore_args = {
139
    'tools': True,
140
    'restore-users': True,
141
    '<users_filename>': 'user_permissions_backup.json',
142
    '--config': None
143
}
144
tools_main(restore_args, settings)
145
```
146

147
### Command Line Usage
148

149
```bash
150
# Pause all alerts
151
grafana-backup tools pause-alerts
152

153
# Unpause alerts from file
154
grafana-backup tools unpause-alerts paused_alerts_202501011200.json
155

156
# Convert users to viewers
157
grafana-backup tools make-users-viewers
158

159
# Restore user permissions
160
grafana-backup tools restore-users user_permissions_backup.json
161
```
162

163
## Tool-Specific Details
164

165
### Alert Pause Operations
166

167
#### Pause Process
168
1. **Discovery**: Retrieves all dashboards and their alert configurations
169
2. **State Capture**: Records current alert enabled/disabled state
170
3. **Bulk Disable**: Disables all enabled alerts while preserving configuration
171
4. **State File**: Creates JSON file with alert details for restoration
172
5. **Validation**: Confirms alerts are successfully paused
173

174
#### Pause State File Format
175
```json
176
{
177
  "timestamp": "2025-01-01T12:00:00Z",
178
  "paused_alerts": [
179
    {
180
      "dashboard_id": 1,
181
      "dashboard_title": "System Metrics",
182
      "alert_id": 1,
183
      "alert_name": "High CPU Usage",
184
      "was_enabled": true
185
    }
186
  ]
187
}
188
```
189

190
#### Unpause Process
191
1. **State File Loading**: Reads previously saved alert state
192
2. **Validation**: Verifies alerts still exist and can be modified
193
3. **Selective Restoration**: Re-enables only alerts that were previously enabled
194
4. **Error Handling**: Reports any alerts that cannot be restored
195
5. **Confirmation**: Validates successful alert restoration
196

197
### User Role Management Operations
198

199
#### Make Users Viewers Process
200
1. **User Discovery**: Retrieves all users in the organization
201
2. **Admin Detection**: Identifies admin users to preserve
202
3. **Role Backup**: Creates backup file with current user roles and permissions
203
4. **Bulk Conversion**: Converts non-admin users to viewer role
204
5. **Validation**: Confirms role changes are applied successfully
205

206
#### User Backup File Format
207
```json
208
{
209
  "timestamp": "2025-01-01T12:00:00Z",
210
  "user_permissions": [
211
    {
212
      "user_id": 2,
213
      "login": "john.doe",
214
      "email": "john.doe@example.com",
215
      "original_role": "Editor",
216
      "is_admin": false,
217
      "org_id": 1
218
    }
219
  ]
220
}
221
```
222

223
#### User Restoration Process
224
1. **Backup File Loading**: Reads previously saved user permission state
225
2. **User Validation**: Verifies users still exist in the system
226
3. **Permission Restoration**: Restores original user roles and permissions
227
4. **Admin Preservation**: Ensures admin users are not downgraded
228
5. **Error Reporting**: Details any users that cannot be restored
229

230
## Authentication Requirements
231

232
### Basic Authentication Needed
233

234
Several tools require basic authentication (username/password) for admin operations:
235

236
- **make-users-viewers**: Requires admin credentials for user role modification
237
- **restore-users**: Requires admin credentials for user permission restoration
238

239
### Configuration Requirements
240

241
```json
242
{
243
  "grafana": {
244
    "admin_account": "admin",
245
    "admin_password": "admin_password"
246
  }
247
}
248
```
249

250
Or via environment variables:
251
```bash
252
export GRAFANA_ADMIN_ACCOUNT="admin"
253
export GRAFANA_ADMIN_PASSWORD="admin_password"
254
# Or pre-encoded
255
export GRAFANA_BASIC_AUTH="YWRtaW46YWRtaW5fcGFzc3dvcmQ="
256
```
257

258
## Safety Features
259

260
### State Preservation
261

262
All tools that modify system state create backup files:
263
- **Alert pause**: Creates alert state file for restoration
264
- **User role changes**: Creates user permission backup file
265
- **Timestamped files**: All backup files include timestamps for tracking
266

267
### Reversible Operations
268

269
All administrative operations are designed to be reversible:
270
- **Pause/Unpause**: Alert states can be fully restored
271
- **Role changes**: User permissions can be completely restored
272
- **Validation**: Operations validate successful completion
273

274
### Error Handling
275

276
Comprehensive error handling for administrative operations:
277
- **API connectivity**: Validates Grafana API access before operations
278
- **Permission validation**: Confirms sufficient privileges for operations
279
- **Partial failure recovery**: Continues with remaining operations if individual items fail
280
- **Detailed logging**: Provides complete audit trail of operations
281

282
## Best Practices
283

284
### Pre-Operation Backup
285

286
Always create a full backup before using administrative tools:
287
```bash
288
# Create full backup first
289
grafana-backup save
290

291
# Then use administrative tools
292
grafana-backup tools pause-alerts
293
```
294

295
### State File Management
296

297
Properly manage state files created by administrative tools:
298
- **Secure storage**: Store state files in secure, backed-up locations
299
- **Naming conventions**: Use descriptive names with timestamps
300
- **Retention policy**: Establish retention policy for state files
301
- **Access control**: Restrict access to state files containing sensitive data
302

303
### Testing in Development
304

305
Test administrative operations in development environments:
306
- **Verify behavior**: Confirm tools work as expected
307
- **Practice restoration**: Test restoration procedures
308
- **Validate safety**: Ensure admin users are preserved
309
- **Timing considerations**: Understand operation duration for maintenance windows
310

311
### Monitoring and Alerting
312

313
Consider the impact of administrative tools on monitoring:
314
- **Alert pause**: Coordinate with monitoring systems during alert pause operations
315
- **User role changes**: Update monitoring access permissions as needed
316
- **Audit logging**: Ensure administrative operations are properly logged
317
- **Change management**: Follow organizational change management procedures
318

319
These administrative tools provide powerful capabilities for operational management while maintaining safety through state preservation and reversible operations.