Skip to content

Commit 6c8bbd3

Browse files
olamilekan000olamilekan000
committed
describe major modes of lima operation
Signed-off-by: olalekan odukoya <[email protected]>
1 parent 96c7179 commit 6c8bbd3

File tree

2 files changed

+314
-0
lines changed

2 files changed

+314
-0
lines changed

‎website/content/en/docs/usage/_index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,12 @@ Then you can connect directly:
7272
ssh lima-default
7373
```
7474

75+
## Understanding Lima's Operation Modes
76+
77+
Lima operates in different modes that affect how it integrates with your host system. By default, Lima runs in "machine mode" which automatically mounts your home directory, forwards ports, and sets up container engines. For users who prefer more control or isolation, "plain mode" is available.
78+
79+
See [Operation Modes](./operation-modes) for a detailed explanation of these modes and when to use each one.
80+
7581
### Shell completion
7682
- To enable bash completion, add `source <(limactl completion bash)` to `~/.bash_profile`.
7783
- To enable zsh completion, see `limactl completion zsh --help`

‎website/content/en/docs/usage/operation-modes.md

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
---
2+
title: Lima Operation Modes
3+
weight: 2
4+
---
5+
6+
Lima operates in different modes that determine how it integrates with your host system and what features are available. Understanding these modes helps you choose the right configuration for your use case and explains some behaviors that might seem surprising at first.
7+
8+
## Overview
9+
10+
Lima provides two primary operation modes:
11+
12+
- **Machine Mode (Default)**: Provides seamless host-guest integration similar to Docker Machine or Podman Machine
13+
- **Plain Mode**: Offers a traditional VM experience with minimal host integration
14+
15+
This document explains both modes in detail to help you understand Lima's default behavior and choose the right mode for your needs.
16+
17+
## Machine Mode (Default)
18+
19+
By default, Lima operates in "machine mode," which is designed to provide seamless integration between the host and guest systems, similar to Docker Machine and Podman Machine. This mode prioritizes convenience and developer productivity by automatically setting up various integrations.
20+
21+
### Key Features of Machine Mode
22+
23+
#### 1. User Mirroring
24+
Lima automatically mirrors your host user information into the guest VM:
25+
26+
- **Username**: Your host username is copied to the guest (with fallback to "lima" if invalid)
27+
- **User ID (UID)**: Your host UID is preserved in the guest for consistent file ownership
28+
- **User Comment/Full Name**: Your host user's full name is copied
29+
- **Home Directory**: A Linux-compatible home directory is created (typically `/home/username.linux`)
30+
31+
This ensures that files you create in the guest have the correct ownership when viewed from the host.
32+
33+
#### 2. Automatic Directory Mounting
34+
Lima automatically mounts key directories from your host:
35+
36+
- **Home Directory Mount**: Your entire home directory (`~`) is mounted read-only at the same path in the guest
37+
- **Shared Workspace**: `/tmp/lima` is mounted as a writable shared space between host and guest
38+
39+
These mounts allow you to:
40+
- Access your host files directly from within the VM
41+
- Share files between host and guest without manual copying
42+
- Maintain a consistent development environment
43+
44+
#### 3. Port Forwarding
45+
Lima automatically forwards ports from the guest to the host:
46+
47+
- Published ports in containers are automatically forwarded to `localhost` on the host
48+
- SSH access is available on a local port (typically 60022 for the "default" instance)
49+
- Network services running in the guest become accessible from the host
50+
51+
#### 4. Container Engine Integration
52+
Lima can automatically install and configure container engines:
53+
54+
- **containerd**: Installed by default in user mode (rootless)
55+
- **Docker/Podman**: Available through templates
56+
- **Kubernetes**: Can be configured through templates like k3s, k8s
57+
58+
#### 5. Guest Agent Services
59+
A guest agent runs inside the VM to:
60+
- Manage port forwarding
61+
- Handle file system mounts
62+
- Coordinate host-guest integration
63+
- Provide status information
64+
65+
### When to Use Machine Mode
66+
67+
Machine mode is ideal for:
68+
- **Container Development**: When you need Docker/Podman/containerd with host integration
69+
- **Development Workflows**: When you want to edit files on the host but run them in Linux
70+
- **Cross-platform Development**: When developing Linux applications on macOS/Windows
71+
- **CI/CD Testing**: When you need a Linux environment that integrates with host tools
72+
73+
### Configuration Example
74+
75+
```yaml
76+
# Machine mode is the default - these settings are applied automatically
77+
user:
78+
# Host user information is automatically mirrored
79+
name: null # Will use your host username
80+
uid: null # Will use your host UID
81+
82+
mounts:
83+
# Home directory mounted read-only
84+
- location: "~"
85+
writable: false
86+
# Shared writable space
87+
- location: "/tmp/lima"
88+
writable: true
89+
90+
containerd:
91+
user: true # Rootless containerd enabled by default
92+
93+
# Port forwarding enabled
94+
# Guest agent enabled
95+
# Host integration enabled
96+
```
97+
98+
## Plain Mode
99+
100+
Plain mode disables Lima's host integration features, providing a more traditional VM experience similar to what users might expect from Vagrant or basic virtualization tools.
101+
102+
### Key Features of Plain Mode
103+
104+
#### 1. No Automatic Mounts
105+
- No home directory mounting
106+
- No shared directories
107+
- You must explicitly configure any mounts you need
108+
109+
#### 2. No Port Forwarding
110+
- Ports are not automatically forwarded from guest to host
111+
- You must manually configure any port forwarding rules
112+
- Network access requires explicit configuration
113+
114+
#### 3. No Container Engine Integration
115+
- containerd is not automatically installed or configured
116+
- No automatic container runtime setup
117+
- You must manually install and configure container engines
118+
119+
#### 4. No Guest Agent
120+
- The Lima guest agent does not run
121+
- No automatic host-guest coordination
122+
- Reduced background processes in the guest
123+
124+
#### 5. Minimal Host Integration
125+
- User information may still be mirrored for SSH access
126+
- Basic VM lifecycle management still works
127+
- SSH access is still available
128+
129+
### When to Use Plain Mode
130+
131+
Plain mode is ideal for:
132+
- **Security-Conscious Environments**: When you want minimal host exposure
133+
- **Traditional VM Usage**: When you prefer explicit control over all integrations
134+
- **Learning/Educational**: When you want to understand Linux systems without abstractions
135+
- **Custom Setups**: When you need full control over the guest environment
136+
- **Isolation**: When you want the guest to be completely separate from the host
137+
138+
### Enabling Plain Mode
139+
140+
To enable plain mode, set the `plain` field to `true` in your Lima configuration:
141+
142+
```yaml
143+
# Enable plain mode
144+
plain: true
145+
146+
# In plain mode, these are automatically disabled:
147+
# - mounts: []
148+
# - portForwards: []
149+
# - containerd.system: false
150+
# - containerd.user: false
151+
# - Guest agent services
152+
```
153+
154+
You can also enable plain mode when creating an instance:
155+
156+
```bash
157+
limactl create --plain my-plain-vm
158+
```
159+
160+
## Comparison: Machine Mode vs Plain Mode
161+
162+
| Feature | Machine Mode | Plain Mode |
163+
|---------|--------------|------------|
164+
| **Home Directory Mount** | ✅ Automatic (`~` read-only) | ❌ None |
165+
| **Shared Directory** | ✅ `/tmp/lima` writable | ❌ None |
166+
| **Port Forwarding** | ✅ Automatic | ❌ None |
167+
| **Container Engine** | ✅ containerd by default | ❌ None |
168+
| **Guest Agent** | ✅ Running | ❌ Disabled |
169+
| **User Mirroring** | ✅ Full mirroring | ✅ Basic (for SSH) |
170+
| **Host Integration** | ✅ Seamless | ❌ Minimal |
171+
| **Security** | ⚠️ More host exposure | ✅ More isolated |
172+
| **Convenience** | ✅ High | ⚠️ Manual setup required |
173+
174+
## Understanding the Default Behavior
175+
176+
### Why Does Lima Auto-Mount the Home Directory?
177+
178+
Lima's default behavior of mounting the home directory is designed to provide a "machine-like" experience similar to Docker Machine or Podman Machine. This design choice:
179+
180+
1. **Enables Seamless Development**: You can edit files on your host with your preferred tools and run them in the Linux environment
181+
2. **Maintains File Ownership**: The UID mirroring ensures files have correct permissions
182+
3. **Reduces Context Switching**: No need to copy files back and forth between host and guest
183+
4. **Supports Container Workflows**: Container images can access host files for development
184+
185+
### Common User Expectations
186+
187+
**Users from Docker Machine/Podman Machine Background** typically expect:
188+
- Automatic host integration
189+
- Seamless file access
190+
- Port forwarding
191+
- Container engine ready to use
192+
193+
**Users from Vagrant Background** might expect:
194+
- Isolated VM environment
195+
- Manual configuration of shared folders
196+
- Explicit port forwarding setup
197+
- No automatic services
198+
199+
### Security Considerations
200+
201+
#### Machine Mode Security Implications
202+
- **Host File Exposure**: Your entire home directory is accessible from the guest
203+
- **Network Exposure**: Ports are automatically forwarded
204+
- **Process Visibility**: Guest agent runs with host integration
205+
206+
#### Plain Mode Security Benefits
207+
- **Isolation**: Guest has minimal access to host resources
208+
- **Explicit Control**: All integrations must be manually configured
209+
- **Reduced Attack Surface**: Fewer automatic services and mounts
210+
211+
## Migration Between Modes
212+
213+
### From Machine Mode to Plain Mode
214+
215+
If you want to disable the automatic integrations:
216+
217+
```yaml
218+
# Disable machine mode features
219+
plain: true
220+
221+
# Or selectively disable features:
222+
plain: false
223+
mounts: [] # No automatic mounts
224+
containerd:
225+
user: false
226+
system: false
227+
portForwards: [] # No automatic port forwarding
228+
```
229+
230+
### From Plain Mode to Machine Mode
231+
232+
To enable machine mode features in a plain mode instance:
233+
234+
```yaml
235+
plain: false
236+
237+
# Re-enable default mounts
238+
mounts:
239+
- location: "~"
240+
- location: "/tmp/lima"
241+
writable: true
242+
243+
# Re-enable containerd
244+
containerd:
245+
user: true
246+
247+
# Port forwarding will be automatic
248+
```
249+
250+
## Best Practices
251+
252+
### For Machine Mode
253+
- **Review Mounted Directories**: Be aware of what host directories are accessible
254+
- **Use Read-Only Mounts**: Keep the home directory read-only unless you need to write
255+
- **Monitor Port Forwarding**: Be aware of which ports are being forwarded
256+
- **Regular Updates**: Keep the guest agent and container engines updated
257+
258+
### For Plain Mode
259+
- **Explicit Configuration**: Document all manual configurations you make
260+
- **Security Review**: Regularly audit what access the VM has to host resources
261+
- **Backup Strategy**: Plan for data persistence since there are no automatic mounts
262+
- **Network Planning**: Design your network access and port forwarding explicitly
263+
264+
### For Both Modes
265+
- **Resource Monitoring**: Monitor CPU, memory, and disk usage
266+
- **Regular Maintenance**: Keep the guest OS and packages updated
267+
- **Configuration Management**: Version control your Lima YAML configurations
268+
- **Testing**: Test your setup in both development and production-like scenarios
269+
270+
## Troubleshooting Common Issues
271+
272+
### "Why is my home directory mounted?"
273+
This is the default behavior in machine mode. If you don't want this:
274+
- Use plain mode (`plain: true`)
275+
- Or remove the home mount: `mounts: []`
276+
277+
### "Why can't I access my files?"
278+
In plain mode, no directories are automatically mounted. You need to:
279+
- Add explicit mounts in your configuration
280+
- Or copy files manually using `limactl copy`
281+
282+
### "Ports aren't being forwarded"
283+
In plain mode, port forwarding is disabled. You need to:
284+
- Add explicit `portForwards` configuration
285+
- Or use plain networking and access the VM's IP directly
286+
287+
### "Container engine isn't available"
288+
In plain mode, container engines aren't automatically installed:
289+
- Install manually: `sudo apt install docker.io` (or similar)
290+
- Or disable plain mode to get automatic containerd
291+
292+
## Related Documentation
293+
294+
- [Configuration Guide](../config/) - Detailed configuration options
295+
- [Filesystem Mounts](../config/mount) - File system mounting options
296+
- [Network Configuration](../config/network/) - Network and port forwarding
297+
- [Port Configuration](../config/port) - Port forwarding configuration
298+
- [Templates](../templates/) - Pre-configured Lima templates
299+
- [FAQ](../faq/) - Frequently asked questions
300+
301+
## Summary
302+
303+
Lima's operation modes provide flexibility for different use cases:
304+
305+
- **Machine Mode (Default)**: Best for development workflows with seamless host-guest integration
306+
- **Plain Mode**: Best for traditional VM usage with explicit control and better isolation
307+
308+
Choose the mode that best fits your security requirements, workflow preferences, and integration needs. You can always switch between modes by modifying your Lima configuration file.

0 commit comments

Comments
 (0)