Manual ENTwinCAT/BSDOperating system2/18/2022 Version: 1.1

Table of contentsTable of contents1 Notes on the documentation . 71.1Symbol explanation . 81.2Documentation issue status . 82 Setup. 92.1Create bootable USB stick . 92.2Check BIOS settings . 102.3Installing TwinCAT/BSD . 103 TwinCAT/BSD. 113.1Credentials . 123.2ZFS properties . 133.3Directory structure . 153.4Write filter. or disabling the write filter . 163.4.2Defining exceptions . 16Text Editors . 164 Network settings. 184.1Setting the IP address . 184.2Changing the host name . 194.3Firewall . and disable firewall . 194.3.2Enable port . 20WLAN . 214.4.1Connecting to WLAN . 214.4.2Configuring as access point. 224.4.3Setting up a DHCP server . 235 Package Server . 245.1Switching to a Chinese server . 245.2Switching to the FreeBSD repository. 255.3Package management. . 265.3.2Install . 265.3.3Update . 275.3.4Uninstall . 275.3.5Lock . 28Update Major Version . 286 Configuration . 296.1User and rights management . 296.1.1Create new user . 306.1.2Edit user information. 316.1.3Deleting a user. 326.2Integrating a USB stick . 336.3Disable real-time Ethernet . 346.4Start services automatically (Autostart) . 35TwinCAT/BSDVersion: 1.13

Table of contents6.5Changing the shell . 357 Remote access . 367.1Remote access with the PuTTY client . 367.2Managing files with the WinSCP client . 377.37.2.1Starting and using the WinSCP client. 377.2.2WinSCP as the root . 387.2.3Opening and editing files . 39Editing the SSH settings . 408 C/C projects for TwinCAT/BSD . 418.1Compiling under TwinCAT/BSD . 419 TwinCAT 3 . 429.1Searching for target systems . 429.2Scan devices . 449.3Changing the AMS NetID . 4510 Restore options . 4610.1 Restore point . 4610.1.1Resetting to factory settings . 4710.1.2Creating a restore point . 4710.1.3Resetting to the restore point. 4810.1.4Using the restore boot environment. 4810.2 Backup and restore . 5010.2.1Creating a backup. 5010.2.2Restoring a backup. 5010.2.3Creating and restoring a backup from the live system. 5111 Error handling and diagnostics. 5211.1 Using kernel messages for diagnosis . 5211.2 Log files . 5211.3 Dumps . 5311.3.1Using automatic process dump . 5311.3.2Creating a process dump manually . 5311.4 Using the ADS monitor . 5411.5 Analyzing network traffic with Wireshark . 5511.6 System repair . 5611.6.1Booting from the USB installer stick . 5611.6.2Start single-user mode. 5712 Appendix . 5812.1 Important commands . 5812.1.1Shell. 5812.1.2File and directory management . 5912.1.3System administration . 6112.1.4Important files and directories. 6312.1.5Text Editors. 6412.1.6Documentation. 6512.2 Bibliography . 664Version: 1.1TwinCAT/BSD

Table of contents12.3 FreeBSD Copyright . 6612.4 Support and Service . 67List of tables. 68List of figures . 69TwinCAT/BSDVersion: 1.15

Table of contents6Version: 1.1TwinCAT/BSD

Notes on the documentation1Notes on the documentationThis description is only intended for the use of trained specialists in control and automation engineering whoare familiar with applicable national standards.It is essential that the documentation and the following notes and explanations are followed when installingand commissioning the components.It is the duty of the technical personnel to use the documentation published at the respective time of eachinstallation and commissioning.The responsible staff must ensure that the application or use of the products described satisfy all therequirements for safety, including all the relevant laws, regulations, guidelines and standards.DisclaimerThe documentation has been prepared with care. The products described are, however, constantly underdevelopment.We reserve the right to revise and change the documentation at any time and without prior announcement.No claims for the modification of products that have already been supplied may be made on the basis of thedata, diagrams and descriptions in this documentation.TrademarksBeckhoff , TwinCAT , TwinCAT/BSD , TC/BSD , EtherCAT , EtherCAT G , EtherCAT G10 , EtherCAT P ,Safety over EtherCAT , TwinSAFE , XFC , XTS and XPlanar are registered trademarks of and licensed byBeckhoff Automation GmbH.Other designations used in this publication may be trademarks whose use by third parties for their ownpurposes could violate the rights of the owners.Patent PendingThe EtherCAT Technology is covered, including but not limited to the following patent applications andpatents:EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702with corresponding applications or registrations in various other countries.EtherCAT is a registered trademark and patented technology, licensed by Beckhoff Automation GmbH,GermanyCopyright Beckhoff Automation GmbH & Co. KG, Germany.The reproduction, distribution and utilization of this document as well as the communication of its contents toothers without express authorization are prohibited.Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of apatent, utility model or design.TwinCAT/BSDVersion: 1.17

Notes on the documentation1.1Symbol explanationThe following warnings are used in the documentation. Read and follow the warnings.Warnings relating to damage to property or the environment:NOTEThere is a potential hazard to the environment and equipment.Notes showing further information or tips:This notice provides important information that will be of assistance in dealing with the product orsoftware. There is no immediate danger to product, people or environment.1.2Version1.01.18Documentation issue statusModificationsFirst VersionChapters TwinCAT/BSD, Network settings, PackageServer, Configuration, Twin-CAT 3, Restore optionsand Error handling and diagnostics reworked.Version: 1.1TwinCAT/BSD

Setup2Setup2.1Create bootable USB stickBefore you can install TwinCAT/BSD on a Industrial PC, you must create a bootable USB stick and uploadthe current image to the USB stick.Use a flash tool such as Rufus to do this. You can then start Industrial PC from the USB stick and installTwinCAT/BSD.Requirements for this step: Download Rufus tool from : Note that more recent versions of Rufus are incompatible with Windows 10 version 21H1. It istherefore recommended to use Rufus 3.13. USB stick with at least 2 GB capacity.Proceed as follows:1. Start the Rufus tool on a PC with Windows operating system.2. Click Select and select the image you want to upload to the USB stick.3. Under Device, select a USB stick as the target drive. If only one external drive is connected to your PC,the USB stick will be selected automatically.Note : Data on the USB stick is irrevocably deleted.4. Click Start to upload the image to the USB stick.ð The process may take a few minutes. Do not cancel the process until the message Ready appears. Youhave successfully created a bootable USB stick and can install TwinCAT/BSD on the Industrial PC in thenext step.TwinCAT/BSDVersion: 1.19

Setup2.2Check BIOS settingsCheck the BIOS settings to be able to start the Industrial PC from the bootable USB stick you created. ForTwinCAT/BSD the boot mode in the BIOS must be set to UEFI or Dual Boot. Use Dual Boot if you wish toswitch between storage media with different operating systems.Start the BIOS setup and adjust the boot mode if the settings on your Industrial PC differ.Proceed as follows:1. Restart your Industrial PC and press [Del] to start the BIOS setup.The BIOS setup window appears.2. Under Boot Boot mode select set the option UEFI or DUAL.3. Press [F4] to save the settings and exit the BIOS setup.The device is restarted.ð You have successfully configured the BIOS and can install the TwinCAT/BSD in the next step.2.3Installing TwinCAT/BSDConnect the bootable USB stick with TwinCAT/BSD image to an Industrial PC and start the device.Requirements: Bootable USB stick with TwinCAT/BSD image. Min. 4 GB free disk space.Proceed as follows:1. Connect the USB stick with the TwinCAT/BSD image to the Industrial PC.2. Start the Industrial PC and press [F7] to enter the boot menu.3. Select the UEFI entry for the USB stick and confirm with [Enter].The Industrial PC boots from the USB stick, and the Beckhoff TwinCAT/BSD installer is executed.4. Select the option TC/BSD Install to install TwinCAT/BSD .5. Set a password and follow the further installation instructions.ð Restart the Industrial PC. TwinCAT/BSD is loaded.10Version: 1.1TwinCAT/BSD

TwinCAT/BSD3TwinCAT/BSDTwinCAT/BSD combines the TwinCAT runtime with FreeBSD, an industrially tested and reliable open sourceoperating system. In addition to multi-core support and a small footprint, TwinCAT/BSD with the BeckhoffPackage Server offers a simple way to install TwinCAT Functions and FreeBSD applications or to update thecomplete system.What is FreeBSDFreeBSD is a Unix-compatible open source operating system directly originating from Berkeley SoftwareDistribution (BSD). As an open source project, FreeBSD is continually being developed further, improvedand optimized by a large group of developers. On account of the generous BSD license, Beckhoff has optedfor FreeBSD, which enables the integration of TwinCAT without licensing problems.FreeBSD is very popular and is used worldwide by renowned companies. A detailed list of users can befound oisFreeBSD supports both x86 and X64 platforms and makes scalable systems possible with ARM CPUsextending up to powerful Xeon CPUs.Further information on FreeBSD can be found on the homepage of the FreeBSD Foundation or that of theFreeBSD supports all TwinCAT 3 runtime functions. The programming is still carried out with thefamiliar Microsoft Visual Studio -based TwinCAT XAE from a Windows development computer. TwinCAT/BSD offers multi-core support, allowing individual cores to also be reserved for the exclusive use ofTwinCAT.Fig. 1: Structure of the TwinCAT 3 Runtime under TwinCAT/BSD.In addition to the TwinCAT HMI Server, an HTML5 web browser can be used as a client for TwinCAT HMI.The configuration takes place as usual via the graphic editor of the TwinCAT XAE development environment.TwinCAT/BSDVersion: 1.111

TwinCAT/BSDSoftware and updatesIn addition to a large number of FreeBSD programs, TwinCAT Functions can also be installed via theBeckhoff Package Server. Moreover, the uncomplicated updating of the operating system as well as theTwinCAT runtime is possible in this way via the network. Software packages can also be installed offline.The software packages are first loaded to a development computer with a network connection and laterinstalled directly on the Beckhoff Industrial PC. The hosting of the customer's own package server on theirside is also possible. Apart from FreeBSD programs that can be offered in this way, many well-knownprograms from Linux are also available: filterAs is familiar from the Windows operating system, TwinCAT/BSD provides a write filter that protects thesystem from persistent changes. With the write filter activated, the system is in a previously defined statefollowing a restart.Backup and restoreA TwinCAT/BSD system can be backed up and restored using a USB stick that offers similar functions as theBeckhoff Service Stick for Windows operating systems. A backup can also be created from the live system,which is backed up locally or via the network to a remote system.3.1CredentialsChanging the standard passwordFor security reasons, change the standard password after logging in for the first time.When TwinCAT/BSD is delivered, a user (Administrator) is available by default, with which you can logon to the console. This user does not have conventional administrator rights like under Windows systems buthas the authority to obtain root rights for certain purposes. Use the doas command to obtain root rights.doas corresponds to the command sudo, a command known from other Unix-like operating systems.Login data: Login: Administrator Password: 1Proceed as follows:1. Start the Industrial PC.2. Log in with the user name Administrator and the password 1.3. After successful login, the user and the host name of the Industrial PC is displayed. For example:CX-1D7BD4.Administrator@CX-1D7BD4 4. Enter the command passwd in order to set a new password for TwinCAT/BSD. Follow the instructions.ð You have successfully logged in and set a new password for TwinCAT/BSD.12Version: 1.1TwinCAT/BSD

TwinCAT/BSD3.2ZFS propertiesZFS is a file system that combines the roles of volume manager and file system. What is special here is thatZFS knows the structure of the storage media and a contiguous memory pool (zpool) is thus available. Thememory pool is divided between the available file systems. As soon as more storage media are added to thepool, the existing file systems automatically grow with them and the new storage space is made available toall file systems.Conventional file systems such as NTFS, ext3 or UFS behave differently. This separates hard disks, RAIDcontrollers, volume managers, and file systems from one another. File systems can only be created on onehard disk at the same time. As soon as a second hard disk is added, two separate file systems have to becreated.Other advantages of ZFS are: RAID functionality is available by default. Switch-off-proof thanks to copy-on-write Automatic data error detection through checksums Convenient backup options through snapshotsFig. 2: Overview of the structure of the memory pool, including storage media and datasets.vDevThe vDevs represent the basic hardware, such as HDDs, SSDs or CFast cards. There are various types ofvDev. A vDev can consist of a hard disk, a group of hard disks, a file, a mirror of two or more hard disks orvarious RAID-Z configurations.If several vDevs are used, then the data will be divided among the available vDevs in order to increase thespeed and to utilize the storage space to the optimum. If one vdev fails, the data of the entire pool is lost.Suitable redundancy (e.g. RAID1) is therefore useful for a vdev.Memory pool (zpool)A memory pool (zpool) consists in turn of one or more vDevs. ZFS is based on a memory pool (zpool), whichis essentially a collection of vDevs. The vDevs for their part represent the basic hardware, such as HDDs,SSDs or CFast cards, which store the data.The vDevs are combined into a memory pool. A memory pool is used when one or more file systems(datasets) or block devices (volumes) are to be created. These datasets and volumes share the storagespace available in the pool.TwinCAT/BSDVersion: 1.113

TwinCAT/BSDDatasetsDataset is the general term for a ZFS file system, volume, snapshot or clone. Any number of datasets can becreated, which are based on a memory pool and contain directories and files. Datasets are hierarchicallybased on one another. There is a root dataset with following parent datasets, child datasets and furthergraduations.The datasets inherit all properties from the parents and grandparents. However, it is also possible to changeand overwrite the default values inherited from the parents and grandparents. For each dataset propertiessuch as compression, write and read access, storage space quotas or network shares can be defined.Example of a dataset:zroot/tmpIn this example, zroot/ is the root dataset and also the name of the memory pool (zpool) under TwinCAT/BSD. The command zfs list can be used to display all available datasets.Fig. 3: Datasets of the TwinCAT/BSD operating system.The dataset zroot/ROOT/defaul contains the basic system, all programs and TwinCAT. The datasetzroot/ROOT/restore is a boot environment that can be used for restoring recovery points and resetting tofactory settings (see Restore options [} 46]). The other datasets are mounted at their respective mountpoints and can be accessed through the file system hierarchy (see Directory structure [} 15]). Datasetsfacilitate customization of options such as read and write permissions for entire memory areas or limitation ofstorage space for log files or the home directory, for example. Furthermore, individual datasets can bebacked up using snapshots.In addition, zfs list specifies the default mount point for each dataset, i.e. the point in the operatingsystem's file system hierarchy through which the dataset can be accessed when it is mounted. Most datasetsare mounted automatically directly after system startup. The command zfs mount displays the datasetsthat are currently mounted. A file system, directory or device is only made accessible to the user when adataset is mounted. The memory pool (zpool) and the associated datasets are mounted in TwinCAT/BSDdirectly after booting.VolumesA volume is a special type of dataset. It is not inserted as a file system and is instead a block device under /dev/zvol/poolname/dataset. This allows the volume to be used for other file systems, to provide thehard disks to a virtual machine or to be exported via protocols such as iSCSI or HAST (Highly AvailableStorage). A volume can be formatted with any file system or it can function as a pure data memory. A volumeappears to the user to be a normal disk with a fixed size.14Version: 1.1TwinCAT/BSD

TwinCAT/BSD3.3Directory structureThe directory structure of TwinCAT/BSD is based on the Filesystem Hierarchy Standard (FHS).Fig. 4: TwinCAT/BSD directory structure.The command cd can be used to navigate to a different directory. cd . moves up one level in the directoryhierarchy, cd /bin moves to the directory /bin. The command ls lists the files in the current directory.Table 1: Overview of important TwinCAT/BSD escriptionRoot directory and top-level directory hierarchy.Basic user applications for single-user and multi-user environments.Kernel, drivers, programs and configuration files for the boot process.Device nodes, which can be used to access hardware directly, for example.System-relevant scripts and configuration files.Link to /usr/home, where the home directories of the users are located./mnt//root/Empty directory; usually serves as a mount point for USB sticks, for example.Home directory of the superuser sic system applications for single-user and multi-user environments.Unix system resources, contains most of the user applications.General applications.Contains header files for C compilers.Local programs and libraries, i.e., software installed by a user, such as softwareunrelated to the basic FreeBSD system itself.Mainly Beckhoff applicationsConfiguration files, TwinCAT directory with TwinCAT Functions and PLCproject.Including ADS header files TcAdsDef.h and TcAdsAPI.hSystem applications that are executed by the user.Variable files, i.e. temporary files with changing content such as log files.Contains system log lude//usr/sbin//var//var/log/Programs that are located in one of the bin or sbin directories can usually be called from the command linewithout specifying the path. They are defined in the shells as environment variables.TwinCAT/BSDVersion: 1.115

TwinCAT/BSD3.4Write filterTwinCAT/BSD has a write filter that protects certain data sets against write access. The advantage of a writefilter is that the user can secure a system in a preconfigured state. Following a restart, the system isautomatically reset to the originally defined state.The dataset zroot/ROOT/default, which contains most of the system and TwinCAT, is protected againstwrite accesses when the write filter is

familiar Microsoft Visual Studio -based TwinCAT XAE from a Windows development computer. TwinCAT/ BSD offers multi-core support, allowing individual cores to also be reserved for the exclusive use of TwinCAT. Fig.