Skip to content

Commit 612f41f

Browse files
yockgenyockgen
authored
Merge pull request #354 from open-edge-platform/pg-dev-add-sysconf
Adding tutorial on custom actions configuration
2 parents 252993d + 8616135 commit 612f41f

1 file changed

Lines changed: 234 additions & 0 deletions

File tree

‎docs/tutorial/configure-additional-actions-for-build.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Configuring Custom Commands During Image Build
2+
3+
## Overview
4+
5+
The OS Image Composer supports executing custom commands during the image build process through the `configurations` section in image template files. These commands are executed in a chroot environment after all packages have been installed, allowing you to customize the system configuration, create files, download resources, or perform any other setup tasks needed for your custom image.
6+
7+
## How It Works
8+
9+
Custom configurations are executed during the rootfs build phase, specifically after customer packages have been installed. The commands run in a chroot environment within the image being built, giving them full access to modify the target system.
10+
11+
## Configuration Structure
12+
13+
The `configurations` section must be placed under `systemConfig` in your image template YAML file, alongside other system configuration options:
14+
15+
```yaml
16+
systemConfig:
17+
name: your-config-name
18+
description: "Your system configuration description"
19+
20+
# Package installation happens first
21+
packages:
22+
- ubuntu-minimal
23+
- systemd
24+
- wget # Required for download commands
25+
- curl # Required for API calls
26+
# ... other packages
27+
28+
# Custom configurations execute after packages are installed
29+
configurations:
30+
- cmd: "touch /etc/dummy01.txt"
31+
- cmd: "echo 'dlstreamer x86_64 ubuntu24 image' > /etc/dummy01.txt"
32+
- cmd: "wget --no-check-certificate -O /etc/validate.sh https://example.com/validate.sh"
33+
```
34+
35+
## Complete Template Structure
36+
37+
Here's how the configurations section fits within a complete image template:
38+
39+
```yaml
40+
image:
41+
name: your-image-name
42+
version: "1.0"
43+
44+
target:
45+
os: ubuntu
46+
dist: ubuntu24
47+
arch: x86_64
48+
imageType: raw
49+
50+
disk:
51+
name: your-disk-config
52+
# ... disk configuration
53+
54+
systemConfig:
55+
name: your-system-config
56+
description: "Custom system configuration"
57+
58+
packages:
59+
- ubuntu-minimal
60+
- systemd-boot
61+
- openssh-server
62+
- wget # Essential for download operations
63+
- curl # For API interactions
64+
- systemd # For systemctl commands
65+
# ... other required packages
66+
67+
kernel:
68+
version: "6.12"
69+
# ... kernel configuration
70+
71+
# Custom configurations - executed after all packages are installed
72+
configurations:
73+
- cmd: "mkdir -p /opt/myapp"
74+
- cmd: "touch /etc/dummy01.txt"
75+
- cmd: "echo 'Custom image marker' > /etc/dummy01.txt"
76+
- cmd: "wget --no-check-certificate -O /etc/validate.sh https://example.com/validate.sh"
77+
- cmd: "chmod +x /etc/validate.sh"
78+
- cmd: "systemctl enable ssh"
79+
```
80+
81+
## Real-World Example
82+
83+
From the [`ubuntu24-mah.yml`](../image-templates/ubuntu24-mah.yml) template:
84+
85+
```yaml
86+
systemConfig:
87+
88+
packages:
89+
...
90+
- wget # Required for wget commands below
91+
92+
configurations:
93+
- cmd: "touch /etc/dummy01.txt"
94+
- cmd: "echo 'dlstreamer x86_64 ubuntu24 image' > /etc/dummy01.txt"
95+
- cmd: "wget --no-check-certificate -O /etc/validate.sh https://raw.githubusercontent.com/open-edge-platform/os-image-composer/main/validate.sh"
96+
```
97+
98+
## Configuration Examples
99+
100+
### Basic File Operations
101+
102+
```yaml
103+
systemConfig:
104+
...
105+
configurations:
106+
- cmd: "mkdir -p /opt/myapp/config"
107+
- cmd: "touch /etc/myconfig.conf"
108+
- cmd: "echo 'CustomApp=enabled' > /etc/myconfig.conf"
109+
- cmd: "chmod 644 /etc/myconfig.conf"
110+
```
111+
112+
### Download and Install Resources
113+
114+
```yaml
115+
systemConfig:
116+
packages:
117+
....
118+
- wget # Required for wget commands
119+
- curl # Required for curl commands
120+
121+
configurations:
122+
- cmd: "wget --no-check-certificate -O /tmp/setup.sh https://example.com/setup.sh"
123+
- cmd: "chmod +x /tmp/setup.sh"
124+
- cmd: "bash /tmp/setup.sh"
125+
- cmd: "curl -o /etc/app.json https://api.example.com/config"
126+
```
127+
128+
## Execution Environment
129+
130+
### Chroot Context
131+
132+
All commands are executed using `chroot` to the image root filesystem. This means:
133+
134+
- Commands run as if the target system is the root filesystem
135+
- All paths are relative to the image being built
136+
- Standard system tools and shell are available
137+
- Network access is available (if needed for downloads)
138+
139+
### Execution Order
140+
141+
The build process follows this sequence:
142+
143+
1. **Package Installation**: All packages listed in `packages` are installed
144+
2. **Custom Configurations**: Commands in `configurations` are executed sequentially
145+
146+
147+
## Best Practices
148+
149+
### 1. Include Required Tools in Packages
150+
151+
Always include the tools your commands need in the `packages` section:
152+
153+
```yaml
154+
systemConfig:
155+
packages:
156+
- wget # For wget commands
157+
- curl # For curl commands
158+
- systemd # For systemctl commands
159+
- coreutils # For basic file operations
160+
- util-linux # For system utilities
161+
162+
configurations:
163+
- cmd: "wget -O /opt/file.txt https://example.com/file.txt"
164+
- cmd: "systemctl enable myservice"
165+
```
166+
167+
### 2. Use Absolute Paths
168+
169+
Always use absolute paths since commands execute in the chroot environment:
170+
171+
```yaml
172+
configurations:
173+
# Good - absolute paths
174+
- cmd: "echo 'config' > /etc/myapp.conf"
175+
- cmd: "mkdir -p /opt/myapp"
176+
177+
# Avoid - relative paths may not work as expected
178+
- cmd: "echo 'config' > myapp.conf"
179+
```
180+
181+
### 3. Make Commands Robust
182+
183+
Add error checking and make commands idempotent:
184+
185+
```yaml
186+
configurations:
187+
- cmd: "mkdir -p /opt/myapp || true"
188+
- cmd: "test -f /etc/config || echo 'default' > /etc/config"
189+
- cmd: "systemctl is-enabled ssh || systemctl enable ssh"
190+
```
191+
192+
### 4. Secure Downloads
193+
194+
Be cautious with downloaded content and verify integrity when possible:
195+
196+
```yaml
197+
systemConfig:
198+
packages:
199+
- wget
200+
- coreutils # For sha256sum
201+
202+
configurations:
203+
- cmd: "wget --no-check-certificate -O /tmp/script.sh https://example.com/script.sh"
204+
- cmd: "echo 'expected-sha256 /tmp/script.sh' | sha256sum -c"
205+
- cmd: "chmod +x /tmp/script.sh && mv /tmp/script.sh /opt/script.sh"
206+
```
207+
208+
## Error Handling
209+
210+
- If any configuration command fails, the entire build process stops
211+
- Error messages are logged with details about which command failed
212+
- Commands should be designed to be idempotent when possible
213+
214+
## Troubleshooting
215+
216+
### Common Issues
217+
218+
1. **Command Not Found**: Ensure required packages are installed in the `packages` section
219+
2. **Permission Denied**: Some operations may require specific user contexts
220+
3. **Network Failures**: Download commands may fail due to network issues
221+
4. **Path Issues**: Use absolute paths for all file operations
222+
223+
## Security Considerations
224+
225+
- Downloaded scripts and files should be from trusted sources
226+
- Avoid hardcoding sensitive information in commands
227+
- Consider using checksums to verify downloaded content
228+
- Be cautious with commands that modify system security settings
229+
230+
## Related Documentation
231+
232+
- [Image Template Format](../architecture/image-template-format.md)
233+
- [Understanding the OS Image Build Process](../architecture/os-image-composer-build-process.md)
234+
- [Command-Line Reference](../architecture/os-image-composer-cli-specification.md)

0 commit comments

Comments
 (0)