Samba does not display files correctly when they contain a colon.

Original file name: test:file.txt

Display name under Windows: T8S6CH~R.TXT

How can I fix it?


Linux: SLES 11 SP 3

Samba: Version 3.6.3-

4 Answers 4


The problem with Samba's mangled names option is that neither setting is ideal. You can have names that are not mangled, but cannot be accessed in any way because they contain illegal characters, or names that are mangled into the DOS 8.3 format and hence close to unreadable.

Fortunately there is (now) a VFS module called catia which will provide custom character mappings. In particular it's possible to map out the characters considered illegal in Windows filenames.

In the [global] section place these lines:

    # Mapping illegal characters, where enabled with "vfs objects = catia"
    mangled names = no
    catia:mappings = 0x22:0xa8,0x2a:0xa4,0x2f:0xf8,0x3a:0xf7,0x3c:0xab,0x3e:0xbb,0x3f:0xbf,0x5c:0xff,0x7c:0xa6

In each [share_name] section add this next line (if you already have a vfs objects line, just append catia to the list):

    vfs objects = catia

As usual, if it's going to apply to all your shares, this share-based setting can be placed in [global] instead of each individual share defintion.

On my Debian-based system this VFS object module was installed as part of the standard package.

One example of a filename that is mapped by this setting is 2017-12-24 12:23.txt. Using mangled names = yes has this file displayed as 2BB0Y9~4.TXT. Using vfs objects = catia instead has this file name displayed as 2017-12-24 12÷23.txt. It's not perfect but it's pretty good. And most importantly, I can access it from Windows applications.

  • 2
    See ⁚ ∶ ׃ ꞉ for other characters that look like ASCII colon. Jul 25, 2017 at 16:29
  • @StéphaneChazelas please do also feel free to submit that as a suggestion to the Samba development team. I just took their suggested list. Jul 25, 2017 at 16:57
  • When I share a folder with Nautilus, the folder does not, obviously, show up in /etc/samba/smb.conf. How can I apply your solution in this scenario? May 19, 2019 at 11:59
  • 2
    Here is another map I came up with, that uses more characters from the General Punctuation and Mathematical Operators plane: 0x22:0x201f,0x2a:0x2217,0x2f:0x2215,0x3a:0x2236,0x3c:0x2039,0x3e:0x203a,0x3f:0xbf,0x5c:0x2216,0x7c:0x2223
    – jangxx
    Jul 5, 2023 at 10:01

For some reason Samba started to mangle the file names containing a colon. That far I could not find anything regarding this behavior in Internet.

The solution is very simple. Adding mangled names = no in the [global] section to /etc/samba/smb.conf and restarting Samba fixed the issue.

  • Great to know that! +1 Jul 29, 2016 at 17:46
  • 5
    This solution is incomplete. Files with illegal Windows characters such as ':' are not shown. See roaima's solution. May 19, 2019 at 12:00

Special characters question mark ? \ < > * etc are illegal in windows filenames and I always avoid using them.

Nevertheless, I have no problem with these characters using my macOS Catalina accessing my FreeNAS-11.3-U1 and SMB/Samba setup. I'm not sure why this setting isn't by default, but you'll have to follow these steps to make it work flawless with MacOS.

In FreeNAS webUI, goto Sharing>SMB>Edit

  1. Choose "advanced mode" and checkmark both catia and fruit in "VFS objects"
  2. Set auxiliary parameter to fruit:encoding = native

Then goto Services and restart SMB


For Mac users wanting to mount Samba volumes hosted on Linux without messed-up characters & filenames:

A snippet from my /etc/samba/smb.conf:

path = /path/to/share
browsable = yes
writable = yes
valid users = nick
create mask = 644
vfs objects = catia fruit streams_xattr
fruit:aapl = yes
fruit:encoding = native

I had to add the last 3 lines in the config above 🔼 to get filenames with characters like ? to map properly between Mac & Linux.

Don't forget to restart your Samba service after changes eg sudo service smbd restart

(This is expanding on the suggestion by @trommegutten with some text for smb.conf rather than FreeNAS settings)

  • Your answer is for mac users, which is not what OP was asking.
    – number9
    Aug 4, 2022 at 15:35
  • 1
    Sure, I get that it was not asked by the OP but the same odd-name problem can happen on Mac (that's how I ended up here), so I figured worth noting that.
    – Nick
    Aug 5, 2022 at 16:08

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .