200 lines
6.0 KiB
Markdown
200 lines
6.0 KiB
Markdown
# api.func Documentation
|
|
|
|
## Overview
|
|
|
|
The `api.func` file provides Proxmox API integration and diagnostic reporting functionality for the Community Scripts project. It handles API communication, error reporting, and status updates to the community-scripts.org API.
|
|
|
|
## Purpose and Use Cases
|
|
|
|
- **API Communication**: Send installation and status data to community-scripts.org API
|
|
- **Diagnostic Reporting**: Report installation progress and errors for analytics
|
|
- **Error Description**: Provide detailed error code explanations
|
|
- **Status Updates**: Track installation success/failure status
|
|
- **Analytics**: Contribute anonymous usage data for project improvement
|
|
|
|
## Quick Reference
|
|
|
|
### Key Function Groups
|
|
- **Error Handling**: `get_error_description()` - Convert exit codes to human-readable messages
|
|
- **API Communication**: `post_to_api()`, `post_to_api_vm()` - Send installation data
|
|
- **Status Updates**: `post_update_to_api()` - Report installation completion status
|
|
|
|
### Dependencies
|
|
- **External**: `curl` command for HTTP requests
|
|
- **Internal**: Uses environment variables from other scripts
|
|
|
|
### Integration Points
|
|
- Used by: All installation scripts for diagnostic reporting
|
|
- Uses: Environment variables from build.func and other scripts
|
|
- Provides: API communication and error reporting services
|
|
|
|
## Documentation Files
|
|
|
|
### 📊 [API_FLOWCHART.md](./API_FLOWCHART.md)
|
|
Visual execution flows showing API communication processes and error handling.
|
|
|
|
### 📚 [API_FUNCTIONS_REFERENCE.md](./API_FUNCTIONS_REFERENCE.md)
|
|
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.
|
|
|
|
### 💡 [API_USAGE_EXAMPLES.md](./API_USAGE_EXAMPLES.md)
|
|
Practical examples showing how to use API functions and common patterns.
|
|
|
|
### 🔗 [API_INTEGRATION.md](./API_INTEGRATION.md)
|
|
How api.func integrates with other components and provides API services.
|
|
|
|
## Key Features
|
|
|
|
### Error Code Descriptions
|
|
- **Comprehensive Coverage**: 50+ error codes with detailed explanations
|
|
- **LXC-Specific Errors**: Container creation and management errors
|
|
- **System Errors**: General system and network errors
|
|
- **Signal Errors**: Process termination and signal errors
|
|
|
|
### API Communication
|
|
- **LXC Reporting**: Send LXC container installation data
|
|
- **VM Reporting**: Send VM installation data
|
|
- **Status Updates**: Report installation success/failure
|
|
- **Diagnostic Data**: Anonymous usage analytics
|
|
|
|
### Diagnostic Integration
|
|
- **Optional Reporting**: Only sends data when diagnostics enabled
|
|
- **Privacy Respect**: Respects user privacy settings
|
|
- **Error Tracking**: Tracks installation errors for improvement
|
|
- **Usage Analytics**: Contributes to project statistics
|
|
|
|
## Common Usage Patterns
|
|
|
|
### Basic API Setup
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Basic API setup
|
|
|
|
source api.func
|
|
|
|
# Set up diagnostic reporting
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
|
|
# Report installation start
|
|
post_to_api
|
|
```
|
|
|
|
### Error Reporting
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Get error description
|
|
error_msg=$(get_error_description 127)
|
|
echo "Error 127: $error_msg"
|
|
# Output: Error 127: Command not found: Incorrect path or missing dependency.
|
|
```
|
|
|
|
### Status Updates
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
source api.func
|
|
|
|
# Report successful installation
|
|
post_update_to_api "success" 0
|
|
|
|
# Report failed installation
|
|
post_update_to_api "failed" 127
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Required Variables
|
|
- `DIAGNOSTICS`: Enable/disable diagnostic reporting ("yes"/"no")
|
|
- `RANDOM_UUID`: Unique identifier for tracking
|
|
|
|
### Optional Variables
|
|
- `CT_TYPE`: Container type (1 for LXC, 2 for VM)
|
|
- `DISK_SIZE`: Disk size in GB
|
|
- `CORE_COUNT`: Number of CPU cores
|
|
- `RAM_SIZE`: RAM size in MB
|
|
- `var_os`: Operating system type
|
|
- `var_version`: OS version
|
|
- `DISABLEIP6`: IPv6 disable setting
|
|
- `NSAPP`: Namespace application name
|
|
- `METHOD`: Installation method
|
|
|
|
### Internal Variables
|
|
- `POST_UPDATE_DONE`: Prevents duplicate status updates
|
|
- `API_URL`: Community scripts API endpoint
|
|
- `JSON_PAYLOAD`: API request payload
|
|
- `RESPONSE`: API response
|
|
|
|
## Error Code Categories
|
|
|
|
### General System Errors
|
|
- **0-9**: Basic system errors
|
|
- **18, 22, 28, 35**: Network and I/O errors
|
|
- **56, 60**: TLS/SSL errors
|
|
- **125-128**: Command execution errors
|
|
- **129-143**: Signal errors
|
|
- **152**: Resource limit errors
|
|
- **255**: Unknown critical errors
|
|
|
|
### LXC-Specific Errors
|
|
- **100-101**: LXC installation errors
|
|
- **200-209**: LXC creation and management errors
|
|
|
|
### Docker Errors
|
|
- **125**: Docker container start errors
|
|
|
|
## Best Practices
|
|
|
|
### Diagnostic Reporting
|
|
1. Always check if diagnostics are enabled
|
|
2. Respect user privacy settings
|
|
3. Use unique identifiers for tracking
|
|
4. Report both success and failure cases
|
|
|
|
### Error Handling
|
|
1. Use appropriate error codes
|
|
2. Provide meaningful error descriptions
|
|
3. Handle API communication failures gracefully
|
|
4. Don't block installation on API failures
|
|
|
|
### API Usage
|
|
1. Check for curl availability
|
|
2. Handle network failures gracefully
|
|
3. Use appropriate HTTP methods
|
|
4. Include all required data
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
1. **API Communication Fails**: Check network connectivity and curl availability
|
|
2. **Diagnostics Not Working**: Verify DIAGNOSTICS setting and RANDOM_UUID
|
|
3. **Missing Error Descriptions**: Check error code coverage
|
|
4. **Duplicate Updates**: POST_UPDATE_DONE prevents duplicates
|
|
|
|
### Debug Mode
|
|
Enable diagnostic reporting for debugging:
|
|
```bash
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="$(uuidgen)"
|
|
```
|
|
|
|
### API Testing
|
|
Test API communication:
|
|
```bash
|
|
source api.func
|
|
export DIAGNOSTICS="yes"
|
|
export RANDOM_UUID="test-$(date +%s)"
|
|
post_to_api
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [core.func](../core.func/) - Core utilities and error handling
|
|
- [error_handler.func](../error_handler.func/) - Error handling utilities
|
|
- [build.func](../build.func/) - Container creation with API integration
|
|
- [tools.func](../tools.func/) - Extended utilities with API integration
|
|
|
|
---
|
|
|
|
*This documentation covers the api.func file which provides API communication and diagnostic reporting for all Proxmox Community Scripts.*
|