Separate filesystem customizations in tcbuild.yaml

Technical Support
, ,
1

I know I can use tcbuild.yaml to configure torizoncore-builder to build my Torizon OS.

With customization.filesystem I can add custom files and so on.

Using isolate as described here all the changes under the same folder (basically /etc) are listed together.

Biut filesystem customizations are done for several reasons (even if with different files under the same /etc/ root folder).

I would like having a clean way to separate the customizations.

As an example:

customization:
  filesystem:
    - network-customizations/
    - other-customizations/
    - usb-customizations/
    - .../

Is this possible?

Since the paths under different root folders could overlap, am I required to take care agains having the same file (with same path) under different folders? Or is there a check mechanism in torizoncore-builder to warn me?

2

Hi, I’m the Toradex AI Assistant.

I might make mistakes or occasionally get you wrong. Our support team will step in if needed.

Yes, you can absolutely separate filesystem customizations in tcbuild.yaml exactly as you’ve shown in your example (1). The customization.filesystem property accepts an array of directories, allowing you to organize your customizations by purpose (2).

How It Works

The filesystem customization in TorizonCore Builder supports multiple directories as you’ve described (2):

customization:
  filesystem:
    - network-customizations/
    - other-customizations/
    - usb-customizations/

(2)

According to the documentation, these directory trees are applied in the listed order (2). This means the directories are merged sequentially onto the base image filesystem.

File Overlap Handling

Regarding your question about overlapping files, the documentation states that the directory trees “will be applied on top of the ones present in the input image, in the listed order” (1)(2). This means:

  1. Later directories override earlier ones - If the same file path exists in multiple directories, the file from the directory listed later in the array will take precedence
  2. No automatic conflict detection - TorizonCore Builder doesn’t appear to provide built-in warnings for file conflicts between your customization directories

Best Practices

To manage potential conflicts effectively:

  • Order matters - List your directories in the order you want them applied, with the most important/final customizations last
  • Organize by function - Your approach of separating by purpose (network, USB, etc.) is exactly what the tool supports
  • Manual conflict checking - You’ll need to manually ensure that critical files aren’t accidentally overwritten by later directories

Project Structure Example

Your project directory structure would look like this (1):

.
├── network-customizations/
│   └── etc/
│       └── network-related-files
├── other-customizations/
│   └── etc/
│       └── other-config-files
├── usb-customizations/
│   └── etc/
│       └── usb-config-files
└── tcbuild.yaml

(1)

This approach gives you the clean separation you’re looking for while leveraging TorizonCore Builder’s built-in support for multiple filesystem customization directories.

Best regards, Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

3

@ToradexAI can I do in the following way?

.
├── customizations/
│   ├── netwotk/
│   │   └── etc/
│   │       └── network-related-files
│   ├── other/
│   │   └── etc/
│   │       └── other-config-files
│   └── usb/
│       └── etc/
│           └── usb-config-files
└── tcbuild.yaml

and accordingly in the tcbuild.yaml, point to the subfolders?

customization:
  filesystem:
    - customizations/network/
    - customizations/other/
    - customizations/usb/

In this way I keep a single customization folder in my source repo, but I can separate the several kinds of customization one level below.

4

Yes, absolutely! Your proposed directory structure and configuration is perfectly valid and actually a very clean approach (1)(2).

Directory Structure

Your proposed structure works exactly as intended:

.
├── customizations/
│   ├── network/
│   │   └── etc/
│   │       └── network-related-files
│   ├── other/
│   │   └── etc/
│   │       └── other-config-files
│   └── usb/
│       └── etc/
│           └── usb-config-files
└── tcbuild.yaml

Configuration File

And the corresponding tcbuild.yaml configuration is correct (2):

customization:
  filesystem:
    - customizations/network/
    - customizations/other/
    - customizations/usb/

How TorizonCore Builder Handles This

TorizonCore Builder runs inside a Docker container and mounts your current directory into it (1). This means it only has access to files within that directory. Since all your customization subdirectories are under the main project directory, they will be accessible to the tool (1).

The filesystem customization property accepts an array of directories, and these directory trees will be applied on top of the base image in the listed order (2). Your approach of organizing everything under a single customizations/ folder with logical subdirectories is an excellent way to maintain organization while keeping everything contained.

Benefits of Your Approach

  • Clean repository structure: Single customizations/ folder keeps everything organized
  • Logical separation: Each type of customization has its own subdirectory
  • Version control friendly: Easy to track changes to specific customization types
  • Maintains order: The sequential application order is still preserved (2)

This structure follows the recommended practice of creating a dedicated project directory that contains everything required for customization (1).

Best regards, Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

5

@ToradexAI I did what I described (subfolders under customizations) but now torizoncore-builder gives the following errors:



=>> Handling output section
setfacl: mtab: No such file or directory
setfacl: shadow: No such file or directory
setfacl: systemd/timesyncd.conf: No such file or directory
setfacl: docker/config.json: No such file or directory
...

for some of the files included in the first subdirectory.

Do you know why?

6

The setfacl errors you’re encountering are related to file permissions and ownership when TorizonCore Builder processes your filesystem customizations (1). This typically happens when the .tcattr file is missing or not properly structured in your customization directories.

Understanding the Issue

When you use the isolate command to capture changes from a device, TorizonCore Builder automatically creates a .tcattr file to preserve file and directory permissions and ownership (1). However, when you manually organize files into separate subdirectories as you’ve done, these .tcattr files may not be present or properly configured.

Solution

You have a few options to resolve this:

Option 1: Use the isolate command for each subdirectory

If you captured these files using isolate, make sure each subdirectory has its own .tcattr file. The documentation states that “in order to keep credentials (files and directories permissions and ownership) the isolate command will create the file /etc/.tcattr which will be automatically used later by the union command” (1).

Option 2: Create .tcattr files manually

If you’re manually organizing files, you may need to create appropriate .tcattr files in each subdirectory to define the correct permissions and ownership for your files.

Option 3: Check your directory structure

Ensure that your customization directories contain the complete directory structure starting from the root. For example, if you have files that should go in /etc/, your structure should be:

customizations/
├── network/
│   └── etc/
│       └── your-network-files
├── other/
│   └── etc/
│       └── your-other-files
└── usb/
    └── etc/
        └── your-usb-files

Debugging Steps

  1. Check for .tcattr files: Look in each of your customization subdirectories to see if .tcattr files exist
  2. Verify file paths: Ensure the files mentioned in the errors (mtab, shadow, etc.) exist in the expected locations within your customization directories
  3. Review the complete error output: The full error log may provide more specific information about which customization directory is causing issues

The filesystem customization feature expects the directory trees to be applied on top of the base image in the listed order (2), so the structure and permissions need to be correctly maintained.

Best regards, Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

1 Like
7

@ToradexAI you’re right. I needed a .tcattr file in the subfolders.

But I have one big doubt at this point: should every file be listed in the .tcattr file? I see that only some of the files were (are) listed. But torizoncore-builder is able to build.

Are there some “special” files that must be listed and other ones than can be missing?

8

I don’t have specific documentation about which files must be listed in the .tcattr file and which ones can be omitted. The available sources mention that the isolate command creates the .tcattr file to preserve file and directory permissions and ownership (1), but they don’t provide details about the criteria for which files get included.

What We Know

From the documentation, the .tcattr file is automatically generated by the isolate command to keep credentials (files and directories permissions and ownership) (1). However, the sources don’t specify:

  • Which files are considered “special” and must be listed
  • What criteria TorizonCore Builder uses to determine which files need permission tracking
  • Why some files can be omitted while others are required

Recommendation

To get the most accurate information about .tcattr file requirements, I’d recommend:

  1. Check the actual .tcattr files generated by the isolate command to see patterns in which files are included
  2. Test incrementally - try building with minimal .tcattr entries and add more if you encounter permission errors
  3. Focus on system-critical files - files like those in /etc/ that affect system configuration likely need proper permissions

Since this appears to be a more detailed implementation question about TorizonCore Builder’s internal behavior that isn’t fully covered in the available documentation, you may find relevant discussions on the Toradex Community by searching for “tcattr” or similar topics.

Would you like me to provide a general answer based on my knowledge instead?

Best regards, Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

9

Greetings @vix,

The behavior surrounding .tcattr is described here: Commands Manual | Toradex Developer Center

To paraphrase. If a file/directory isn’t explicltly listed in that sub-directories .tcattr there is a default behavior for what permissions and attributes the file/directory will have.

Best Regards,
Jeremias