0
# Configuration Management
1

2
PM2 configuration management capabilities for getting, setting, and persisting configuration values. Includes state persistence operations for saving and restoring process configurations across system restarts.
3

4
## Capabilities
5

6
### Configuration Operations
7

8
Manage PM2 configuration settings including runtime and persistent configuration.
9

10
```javascript { .api }
11
/**
12
 * Get PM2 configuration value
13
 * @param key - Configuration key (optional, returns all config if not provided)
14
 * @param callback - Called with configuration value
15
 */
16
function get(key?: string, callback?: (err: Error) => void): void;
17

18
/**
19
 * Set PM2 configuration value
20
 * @param key - Configuration key
21
 * @param value - Configuration value
22
 * @param callback - Called when value is set
23
 */
24
function set(key: string, value: any, callback?: (err: Error) => void): void;
25

26
/**
27
 * Set multiple PM2 configuration values
28
 * @param values - Configuration values as string
29
 * @param callback - Called when values are set
30
 */
31
function multiset(values: string, callback?: (err: Error) => void): void;
32

33
/**
34
 * Unset PM2 configuration value
35
 * @param key - Configuration key to unset
36
 * @param callback - Called when value is unset
37
 */
38
function unset(key: string, callback?: (err: Error) => void): void;
39
```
40

41
**Usage Examples:**
42

43
```javascript
44
// Get specific configuration value
45
pm2.get('pm2_home', (err) => {
46
  if (err) throw err;
47
  console.log('PM2 home directory retrieved');
48
});
49

50
// Get all configuration
51
pm2.get((err) => {
52
  if (err) throw err;
53
  console.log('All configuration retrieved');
54
});
55

56
// Set configuration value
57
pm2.set('log-date-format', 'YYYY-MM-DD HH:mm:ss Z', (err) => {
58
  if (err) throw err;
59
  console.log('Log date format updated');
60
});
61

62
// Set multiple values
63
pm2.multiset('log-date-format="YYYY-MM-DD" max-memory-restart=1G', (err) => {
64
  if (err) throw err;
65
  console.log('Multiple configuration values set');
66
});
67

68
// Remove configuration value
69
pm2.unset('log-date-format', (err) => {
70
  if (err) throw err;
71
  console.log('Log date format unset');
72
});
73
```
74

75
### State Persistence
76

77
Save and restore PM2 process configurations for system restart recovery.
78

79
```javascript { .api }
80
/**
81
 * Save current process list to dump file
82
 * @param callback - Called when dump is saved
83
 */
84
function dump(callback: (err: Error, result: any) => void): void;
85

86
/**
87
 * Restore processes from dump file
88
 * @param callback - Called when processes are restored
89
 */
90
function resurrect(callback: (err: Error, result: any) => void): void;
91

92
/**
93
 * Clear saved dump file
94
 * @param callback - Called when dump is cleared
95
 */
96
function clearDump(callback: (err: Error, result: any) => void): void;
97

98
/**
99
 * Enable or disable automatic dumping
100
 * @param callback - Called when autodump setting is configured
101
 */
102
function autodump(callback: (err: Error, result: any) => void): void;
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
// Save current process configuration
109
pm2.dump((err, result) => {
110
  if (err) throw err;
111
  console.log('Process list saved to dump file');
112
});
113

114
// Restore processes from saved configuration
115
pm2.resurrect((err, result) => {
116
  if (err) throw err;
117
  console.log('Processes restored from dump file');
118
});
119
```
120

121
### Module Management
122

123
Install and manage PM2 modules for extending functionality.
124

125
```javascript { .api }
126
/**
127
 * Install PM2 module
128
 * @param module_name - Name of module to install
129
 * @param options - Installation options
130
 * @param callback - Called when installation completes
131
 */
132
function install(module_name: string, options?: InstallOptions, callback?: (err: Error) => void): void;
133

134
/**
135
 * Uninstall PM2 module
136
 * @param module_name - Name of module to uninstall
137
 * @param callback - Called when uninstallation completes
138
 */
139
function uninstall(module_name: string, callback?: (err: Error) => void): void;
140

141
interface InstallOptions {
142
  /** Install from tarball */
143
  tarball?: boolean;
144
  /** Perform installation */
145
  install?: boolean;
146
  /** Docker mode */
147
  docker?: boolean;
148
  /** Use v1 API */
149
  v1?: boolean;
150
  /** Safe mode installation */
151
  safe?: boolean | number;
152
}
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Install module
159
pm2.install('pm2-logrotate', (err) => {
160
  if (err) throw err;
161
  console.log('Module installed successfully');
162
});
163

164
// Install with options
165
pm2.install('pm2-server-monit', { safe: true }, (err) => {
166
  if (err) throw err;
167
  console.log('Module installed in safe mode');
168
});
169

170
// Uninstall module
171
pm2.uninstall('pm2-logrotate', (err) => {
172
  if (err) throw err;
173
  console.log('Module uninstalled successfully');
174
});
175
```
176

177
### Utility Services
178

179
Additional utility functions for static file serving and system integration.
180

181
```javascript { .api }
182
/**
183
 * Serve static files
184
 * @param path - Path to serve files from
185
 * @param port - Port number (default: 8080)
186
 * @param options - Serve options
187
 * @param callback - Called when server starts
188
 */
189
function serve(path?: string, port?: number, options?: ServeOptions, callback?: (err: Error) => void): void;
190

191
interface ServeOptions {
192
  /** Single Page Application mode */
193
  spa?: boolean;
194
  /** Basic authentication username */
195
  basic_auth_username?: string;
196
  /** Basic authentication password */
197
  basic_auth_password?: string;
198
  /** Monitor URL path */
199
  monitor?: string;
200
}
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
// Serve current directory on default port
207
pm2.serve((err) => {
208
  if (err) throw err;
209
  console.log('Static file server started on port 8080');
210
});
211

212
// Serve specific directory on custom port
213
pm2.serve('./public', 3000, (err) => {
214
  if (err) throw err;
215
  console.log('Static file server started on port 3000');
216
});
217

218
// Serve with options
219
pm2.serve('./dist', 8080, {
220
  spa: true,
221
  basic_auth_username: 'admin',
222
  basic_auth_password: 'secret'
223
}, (err) => {
224
  if (err) throw err;
225
  console.log('SPA server started with basic auth');
226
});
227
```
228

229
### Version and System Information
230

231
Get PM2 version and system information.
232

233
```javascript { .api }
234
/**
235
 * Get PM2 version information
236
 * @param callback - Called with version information
237
 */
238
function getVersion(callback?: (err: Error) => void): void;
239

240
/**
241
 * Test connection to PM2 daemon
242
 * @param callback - Called with ping result
243
 */
244
function ping(callback?: (err: Error) => void): void;
245

246
/**
247
 * Update PM2 daemon
248
 * @param callback - Called when update completes
249
 */
250
function update(callback?: (err: Error) => void): void;
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
// Get PM2 version
257
pm2.getVersion((err) => {
258
  if (err) throw err;
259
  console.log('PM2 version retrieved');
260
});
261

262
// Test daemon connection
263
pm2.ping((err) => {
264
  if (err) {
265
    console.log('PM2 daemon not responding');
266
  } else {
267
    console.log('PM2 daemon is running');
268
  }
269
});
270

271
// Update PM2 daemon
272
pm2.update((err) => {
273
  if (err) throw err;
274
  console.log('PM2 daemon updated');
275
});
276
```
277

278
## Common Configuration Keys
279

280
PM2 supports various configuration keys that can be managed through the configuration API:
281

282
- `pm2_home` - PM2 home directory path
283
- `log-date-format` - Timestamp format for logs
284
- `max-memory-restart` - Global memory restart threshold
285
- `kill-timeout` - Global kill timeout in milliseconds
286
- `restart-delay` - Global restart delay in milliseconds
287
- `daemon` - Daemon mode setting
288
- `instances` - Default number of instances
289
- `exec-mode` - Default execution mode
290
- `watch` - Default file watching setting
291
- `ignore-watch` - Default ignore patterns for watching
292
- `merge-logs` - Default log merging setting
293
- `log-type` - Log output type
294
- `log-rotate` - Log rotation settings
295

296
## Ecosystem Files
297

298
PM2 supports ecosystem files (JavaScript or JSON) for complex configuration management:
299

300
### JavaScript Ecosystem File (ecosystem.config.js)
301

302
```javascript
303
module.exports = {
304
  apps: [{
305
    name: 'app',
306
    script: './app.js',
307
    instances: 'max',
308
    exec_mode: 'cluster',
309
    env: {
310
      NODE_ENV: 'development'
311
    },
312
    env_production: {
313
      NODE_ENV: 'production',
314
      PORT: 3000
315
    }
316
  }],
317
  deploy: {
318
    production: {
319
      user: 'ubuntu',
320
      host: ['192.168.1.100'],
321
      ref: 'origin/master',
322
      repo: 'git@github.com:username/repository.git',
323
      path: '/var/www/production',
324
      'post-deploy': 'npm install && pm2 reload ecosystem.config.js --env production'
325
    }
326
  }
327
};
328
```
329

330
### JSON Ecosystem File (ecosystem.json)
331

332
```json
333
{
334
  "apps": [{
335
    "name": "worker",
336
    "script": "worker.js",
337
    "instances": 2,
338
    "exec_mode": "fork",
339
    "watch": true,
340
    "ignore_watch": ["node_modules", "logs"],
341
    "max_memory_restart": "1G",
342
    "env": {
343
      "NODE_ENV": "development"
344
    },
345
    "env_production": {
346
      "NODE_ENV": "production"
347
    }
348
  }]
349
}
350
```
351

352
## Core Types
353

354
```javascript { .api }
355
interface InstallOptions {
356
  /** Install from tarball */
357
  tarball?: boolean;
358
  /** Perform installation (default: true) */
359
  install?: boolean;
360
  /** Docker mode */
361
  docker?: boolean;
362
  /** Use v1 API */
363
  v1?: boolean;
364
  /** Safe mode installation */
365
  safe?: boolean | number;
366
}
367

368
interface ServeOptions {
369
  /** Single Page Application mode */
370
  spa?: boolean;
371
  /** Basic authentication username */
372
  basic_auth_username?: string;
373
  /** Basic authentication password */
374
  basic_auth_password?: string;
375
  /** Monitor URL path */
376
  monitor?: string;
377
}
378
```