Australian cloud for business software — built and run in Sydney since 2003

+61 2 8282 5656
support@netleverage.com
Talk to an engineer
Talk to an engineer
NetLeverage
NetLeverage

Restoring Linux files to Windows or SMB: the names, case and characters that do not survive

Technical article
Backup & Recovery

Originally published:

About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.

A restore usually goes back to the kind of system the data came from. Sometimes it cannot. The Linux file server is gone and the replacement is Windows. A NAS share is being moved to a Windows file server. Someone needs a folder from a Linux backup on their Windows laptop today.

Even when file contents can be copied, their names may not survive unchanged. Linux and Windows follow different naming rules, and a name that is perfectly valid on one can be rejected, altered or confused with another file on the other.

This guide sets out both rule sets from their primary documentation, explains what Samba does when it stands between them, and suggests how to plan a restore across the boundary.

Why it matters

A naming inventory matters even when most files look ordinary. Engineering and design software, scripts, exported reports and users on Mac or Linux desktops all create names that Windows does not accept. When those files are restored to Windows, a restore job may skip them, stop with an error, or, worse, restore two files to one name.

The failure can also be quiet. A file restored under a changed name looks present, but links, scripts and databases that refer to the original name no longer find it.

How it works

The Linux rule: almost anything goes

POSIX, the standard Linux follows here, defines a filename as "A sequence of bytes consisting of 1 to {NAME_MAX} bytes used to name a file. The bytes composing the name shall not contain the or characters."

Our reading: apart from the slash and the null byte, a Linux file name may contain colons, question marks, asterisks, backslashes, quotation marks, control characters, a trailing space or a trailing dot. Case matters: Report.txt and report.txt are two different files.

POSIX also defines a much smaller "Portable Filename Character Set": letters, digits and "the , , and characters". That set improves POSIX portability but does not make a name safe on every target: CON, trailing periods, length limits and case collisions still need separate Windows checks. Most real file servers hold many names outside it.

The Windows rules: reserved characters, names and endings

Microsoft's Naming Files, Paths, and Namespaces page lists what a Windows name may not contain. It allows "any character in the current code page for a name, including Unicode characters", except:

  • the reserved characters < >: / \ | ? * and the double quotation mark;
  • "Integer value zero, sometimes referred to as the ASCII NUL character";
  • "Characters whose integer representations are in the range from 1 through 31, except for alternate data streams where these characters are allowed";
  • "Any other character that the target file system does not allow."

It also reserves device names: "CON, PRN, AUX, NUL, COM1" through "COM9" and "LPT1" through "LPT9", plus superscript-digit forms. It adds: "Also avoid these names followed immediately by an extension; for example, NUL.txt and NUL.tar.gz are both equivalent to NUL."

And it warns about endings: "Do not end a file or directory name with a space or a period. Although the underlying file system may support such names, the Windows shell and user interface does not."

Our reading: a Linux folder can hold any of these, legitimately. A file called aux.c in a source tree, notes. with a trailing dot, or Q3: results.xlsx with a colon is ordinary on Linux and a problem on Windows.

Case: two files, one name

The same page says: "Do not assume case sensitivity. For example, consider the names OSCAR, Oscar, and oscar to be the same, even though some file systems (such as a POSIX-compliant file system) may consider them as different." It adds that "NTFS supports POSIX semantics for case sensitivity but this is not the default behavior."

Microsoft's WSL case sensitivity page describes historical access problems with names that differ only in case, then documents per-directory case sensitivity and its application-compatibility limits. The historical example must not be read as a guarantee that every current Windows application behaves identically.

Windows can mark a single directory as case sensitive, but the page attaches warnings:

  • "Some Windows applications, using the assumption that the file system is case insensitive, don't use the correct case to refer to files."
  • "if Windows applications create new directories in a directory tree where you are using case sensitive files, these directories are not case sensitive."
  • "A directory must be empty in order to change the case sensitivity flag attribute on that directory."
  • Changing it requires administrator rights.

Our reading: for a restore, the per-directory flag must be set before the files arrive, on each directory that needs it, and it may break the Windows applications that will use the files. For most business data it is better to resolve case collisions by renaming than by changing Windows behaviour.

Path length

Linux paths are often long, especially in deep project trees. Microsoft's Maximum Path Length Limitation page says: "In the Windows API (with some exceptions discussed in the following paragraphs), the maximum length for a path is MAX_PATH, which is defined as 260 characters." It gives a familiar example: "you may hit this limitation if you are cloning a git repo that has long file names into a folder that itself has a long name."

Longer paths are possible. The naming page says that from Windows 10 version 1607, "changing a registry key or using the Group Policy tool is required to remove the limit." For the Windows 10 version 1607 long-path opt-in, the path-length page requires both the operating-system setting and an application manifest declaring longPathAware. The setting alone does not update every restore tool. The page also describes an extended form that allows "a maximum total path length of 32,767 characters", with each component commonly limited to "255 characters". It notes that "relative paths are always limited to a total of MAX_PATH characters."

Our reading: whether a long path restores depends on the tool doing the restore and on the settings of the target, not just on the file system. Restoring into a shallow folder such as a drive's top level gives the most room.

Samba in the middle: mangled names

Many Linux servers and NAS devices share files to Windows through Samba. Samba has to present Linux names to Windows clients, so it changes the ones Windows cannot handle. The smb.conf(5) manual, for Samba 4.25.0, describes this as name mangling.

The mangled names setting controls whether names Windows cannot use are mapped to "DOS-compatible names" and shown, or "should simply be ignored." Its default is illegal, which "does mangling for names with illegal NTFS characters", which the manual calls "the most sensible setting for modern clients".

The manual describes generated short names using part of the original name and an encoded suffix. Do not turn its algorithm example or collision estimate into a guarantee for every Samba build and configured mangling method. Capture the actual presented names and original share settings, because users may have stored those generated names in links or application data.

Our reading: a Windows user may have saved, linked or scripted a mangled name (an illustrative example would look like Q3RES~A7.XLS) without knowing the real name on the server. That alias is a product of the share's name-mangling rules, rather than the original on-disk filename. If the files are restored to a Windows server, the restored file has a different name, and the user's link breaks.

The manual also warns about changing the mangling method: "Many Win32 applications store the mangled names and so changing to algorithms must not be done lightly as these applications may break unless reinstalled." Our recommendation: when rebuilding a Samba server for a restore, keep the original server's mangling settings.

Samba and case

The smb.conf manual describes case-preserving, generally case-insensitive service and the case sensitive = auto setting. Some explanatory text still names Samba 3.0 and Windows NT. Treat those historical statements as context, then verify the negotiated client behaviour, current server configuration and target application rather than asserting that modern Windows never supports case-sensitive names.

Our reading: on a Samba share, a Windows client has the same difficulty with two files that differ only by case as it would on Windows. Case-insensitive access can already hide the distinction on the Linux share. A careless copy can overwrite one file, while a collision-aware restore can preserve both under reviewed names.

Character mapping: vfs_catia and Mac clients

Some Samba servers go further and translate characters. The vfs_catia(8) page says the CATIA CAD package "commonly creates filenames that use characters that are illegal in CIFS filenames", and the module "implements a character mapping so that these files can be shared with CIFS clients". Each mapping turns a server-side character into a different character for the client, and "The same mapping occurs in the opposite direction."

The page's caveat matters for anyone restoring such data: "Character mapping must work in BOTH directions (server -> client and client -> server) to get unique and existing file names!" Its example of a broken mapping turns a colon into an underscore, so that a name containing a real underscore comes back from the client with a colon in it, and the page says an error such as file not found is returned.

Mac clients do something similar of their own accord. The vfs_fruit(8) page says "OS X maps NTFS illegal characters to the Unicode private range in SMB requests." Its fruit:encoding option controls how they are stored: the default, private, will "store characters as encoded by the OS X client: mapped to the Unicode private range", while native stores "their native ASCII value" and "requires the use of vfs_catia".

Our reading: on a share used by Macs, the names on the Linux disk may contain private-range characters that look odd in a Linux listing but are correct for Mac clients. On a share with catia or fruit native encoding, the disk holds real colons and question marks that Windows clients only ever saw translated. A restore that bypasses Samba, copying straight from the backup to a Windows server, sees the names as they are on disk, not as users saw them.

Unicode needs a separate compatibility check

The cited Windows path APIs do not normalise names for applications. The path length page says "the file system treats path and file names as an opaque sequence of WCHARs." Different forms of the same accented letter are therefore different names. Linux filenames are byte sequences, so encoding conversion is an additional boundary. Preserve the original names and record any translation; this article focuses on Windows naming rules rather than attempting a universal Unicode conversion procedure.

A planning checklist

These are our recommendations, drawn from the sources above.

  1. Inventory names before the restore. On the backup or a restored Linux copy, list names that contain Windows-reserved characters, control characters, reserved device names, or a trailing space or dot. List any names that differ only by case within the same folder, and paths close to 260 characters.
  2. Know how users saw the data. Record whether the original share used mangled names, vfs_catia mappings or vfs_fruit encoding, and keep a copy of the share settings.
  3. Prefer the same kind of target first. Where you can, restore to a Linux server and present it through Samba with the original settings. Users then see the same names they saw before.
  4. If the target must be Windows, decide on a renaming rule in advance, apply it to a copy of the restored data, and keep a list mapping old names to new.
  5. Keep an untouched archive of the original names, so nothing is lost if a renamed file is later needed exactly.
  6. Resolve case collisions deliberately. Decide which file keeps the name, or rename both. Do not let a copy tool decide by overwriting.
  7. Read the restore tool's skip and error report and reconcile file counts. A restore that reports success while skipping names is the outcome to rule out.
  8. Check links and references. Shortcuts, scripts, spreadsheets with external links and databases that store paths may need updating after renaming.

Risks and limits

  • Linux names allow characters Windows rejects, including reserved device names and trailing dots or spaces.
  • Case collisions can make files indistinguishable to case-insensitive Windows applications.
  • Mangled aliases depend on server rules; links can break when the target presents different names.
  • Character mappings must be reversible, or names change on a round trip.
  • Path limits depend on the tool and target settings.
  • Nothing here was run. Behaviour is quoted from the documentation for planning; test with a copy of real data on non-production systems.

Sources

This article was originally published on .