Attach a Serial Line Discipline with ldattach

ldattach turns a plain serial port into a PPS clock source, an SLIP link or a GSM modem channel by attaching a Linux line discipline to it. This walkthrough covers a controlled attach, keeping the device open while it is in use, and detaching cleanly afterwards. The examples use the installed ldattach binary from util-linux 2.41.3, but the local manual page is generated from util-linux 2.39.3, so confirm the help output on the machine where you will run a real setup.

Allow about twenty minutes for a first test, plus time to identify the correct serial hardware and protocol settings. You need a serial device, its documented line settings, the required kernel support, and a shell. Most real attachments need elevated privileges because serial devices are commonly restricted to root or a hardware-access group.

1. Confirm the installed command

Start with checks that only read, never open a device or change state:

$ command -v ldattach
/home/linuxbrew/.linuxbrew/sbin/ldattach
$ ldattach --version
ldattach from util-linux 2.41.3
$ ldattach --help

• Option names. The help output shows exactly which flags and line discipline names this binary accepts.
• Command shape. The basic form is always ldattach <ldisc> <device>.
• Trust your own output. If yours differs from an example you found online, treat the local help as the contract, not the example.

2. Identify the serial device and its owner

List likely serial devices without changing them:

$ ls -l /dev/ttyUSB0 /dev/ttyACM0 2>/dev/null
$ readlink -f /dev/serial/by-id/YOUR-DEVICE-ID 2>/dev/null

Swap in a path that actually exists on your machine. A stable /dev/serial/by-id/ path is usually easier to reason about than a device number, which can shift when things get unplugged and reconnected. Nothing printed? Stop and chase down discovery, cabling and permissions before you reach for sudo.

Next, check whether another process already has the device open:

$ fuser -v /dev/ttyUSB0

No output means fuser found nothing to report. If it lists a service or terminal program, decide carefully whether stopping that program is safe. Do not kill an unknown process just to force the attachment through.

3. Match the line discipline to the protocol

ldattach accepts a line discipline by name or number. The manual lists, among others:

• TTY 0
• SLIP 1
• PPP 3
• HDLC 13
• HCI 15
• PPS 18
• GSM0710 21

Which of these are actually available depends on your kernel release. Use the protocol documentation for the device itself, not a guess based on the driver's name.

A PPS source, for example, might use:

$ sudo ldattach PPS /dev/ttyUSB0

The command normally backgrounds itself once it has opened the device and attached the discipline, and the device has to stay open for the discipline to remain loaded. Treat this as a template: swap in both real values, and confirm the device genuinely emits PPS data before you run it. Do not point it at a random serial port just to see what happens.

4. Set serial parameters before attaching

When the source needs non-default serial settings, pass them explicitly:

• Baud rate. --speed.
• Character size. --sevenbits or --eightbits.
• Parity. --noparity, --evenparity or --oddparity.
• Stop bits. --onestopbit or --twostopbits.

$ sudo ldattach \
    --speed 115200 \
    --eightbits \
    --noparity \
    --onestopbit \
    GSM0710 /dev/ttyUSB0

Use the exact settings the modem or adapter documentation specifies, including the speed. These switches configure the serial line; they do not convert one protocol into another that happens to be compatible. The GSM0710 example above only suits a modem already switched into GSM 07.10 multiplexing mode.

If the device needs an initial command first, --intro-command sends it before ldattach runs. The manual gives AT+CMUX=0\r as a common GSM0710 example. Treat this as security-sensitive device input: check the modem's own documentation, quote the shell argument properly, and never send a command copied from an untrusted source.

$ sudo ldattach \
    --intro-command 'AT+CMUX=0\r' \
    --pause 1 \
    GSM0710 /dev/ttyUSB0

The pause is in seconds and defaults to one. Change it only when the device documentation says to. Neither the intro command nor the pause removes the need to have the modem correctly configured in the first place.

5. Keep it in the foreground while testing

Use --debug for a first controlled test. It keeps ldattach in the foreground and prints progress to standard error, so Ctrl-C stops it instead of you hunting for a background process:

$ sudo ldattach --debug --speed 115200 --eightbits --noparity --onestopbit \
    PPS /dev/ttyUSB0

How chatty the diagnostics are varies by util-linux version and device, and a clean start can be near-silent. Keep the terminal open while you check whatever is actually consuming the line discipline. Press Ctrl-C to stop this foreground process; that closes its device and detaches the discipline.

A quiet terminal is not proof the protocol works. Verify at the layer that actually consumes the data: for a PPS setup, that is likely the time service's own status command; for a modem multiplex, check the expected virtual channels with the modem software. The right verification command depends on the device, and ldattach does not supply it for you.

6. Verify and stop a background attachment

Without --debug, find the process after starting it:

$ pgrep -a -x ldattach
12345 ldattach PPS /dev/ttyUSB0

That process ID and command line are examples. Confirm the device and discipline shown before you stop anything. No matching process? Check the command's error output and work out whether it exited because the device, discipline or permissions were wrong.

To detach the line discipline, terminate the matching ldattach process:

$ sudo kill 12345
$ pgrep -a -x ldattach || echo 'ldattach is no longer running'

7. Diagnose the usual failures

• Permission denied. Usually means your account cannot open the device. Check its group and your own membership:

  $ ls -l /dev/ttyUSB0
  $ id

  Use the host's normal device-access policy. Running with sudo can prove that permissions were the immediate problem, but it does not fix ownership or make a service account production-ready.
• Unknown line discipline. Could be a spelling mistake, a kernel that lacks that discipline, or a util-linux build with a different supported set. Recheck ldattach --help and the running kernel's documentation. Do not substitute a numeric value unless you have verified it for the target kernel.
• Starts but no useful data. Usually a protocol or serial-setting mismatch. Stop it, put the device back into its documented mode, and retry with one deliberate change at a time. If you sent an intro command, remember the modem may now be sitting in a different mode until it is reset or reconfigured.