Skip to content

Commit b378692

Browse files
authored
Revise PIE and immediate binding docs (#2679)
* Revise PIE and immediate binding docs * Update migration guide note: not just applicable GOARCHes, simply configs * Fix note about fully static executable vs. PIE
1 parent 04603c3 commit b378692

2 files changed

Lines changed: 27 additions & 9 deletions

File tree

‎eng/doc/AdditionalFeatures.md‎

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,31 +17,49 @@ See also the [Data Collection policy for the Microsoft build of Go](/README.md#d
1717
## Position-independent executables on Linux
1818

1919
Starting with Go 1.28, the default build mode on Linux is `pie` on architectures that support internally linked position-independent executables: amd64, arm64, loong64, ppc64, ppc64le, and s390x.
20+
Other architectures continue to use the upstream default `exe`.
2021
The PIE default aligns with Microsoft's security policies and enables address space layout randomization (ASLR) for executables.
21-
Windows and macOS (`darwin`) binaries already used PIE by default.
22-
Other Linux architectures and builds using `-race` or `-asan` retain the upstream default of `exe`.
23-
Keeping `-asan` builds non-PIE preserves compatibility with system AddressSanitizer runtimes.
22+
23+
> [!NOTE]
24+
> Windows and macOS (`darwin`) binaries already used PIE by default, prior to Go 1.28.
25+
26+
Builds on Linux using `-race` or `-asan` continue to use `exe` by default, not `pie`.
27+
We do this because Go does not support PIE with the race detector on Linux, and using `pie` with `-asan` may break compatibility with system AddressSanitizer runtimes.
2428

2529
The default applies to `go build`, `go install`, `go run`, and `go test`, including cross-compilation.
2630
It is independent of system crypto and does not require cgo or a C compiler.
2731
Explicit build modes are unchanged; use `-buildmode=exe` to opt out.
2832

29-
Programs without direct or indirect dependencies on Go's `crypto` packages now also require a dynamic loader at runtime.
30-
To keep such programs fully static, for example to run in a container without a dynamic loader, use:
33+
On builds affected by the new PIE default, even programs without crypto dependencies require a dynamic loader at runtime.
34+
For programs without direct or indirect dependencies on Go's `crypto` packages, use the following command to produce a fully static executable:
3135

3236
```sh
3337
CGO_ENABLED=0 go build -buildmode=exe
3438
```
3539

40+
Programs using systemcrypto still require shared libraries and a dynamic loader, even with `CGO_ENABLED=0`.
41+
See [No-cgo OpenSSL backend runtime dependencies](./NocgoOpenSSL.md#runtime-dependencies).
42+
3643
## Immediate binding for ELF binaries
3744

3845
Starting with Go 1.28, the linker enables immediate symbol binding (`BIND_NOW`) by default for dynamically linked ELF executables and shared libraries to align with Microsoft's security policies.
3946
This applies to internal and external linking, with or without cgo or system crypto.
4047

48+
Go produces ELF binaries on Linux and several other Unix-like operating systems.
49+
Windows and macOS use different executable formats and are unaffected.
50+
51+
Statically linked ELF binaries are unaffected by this change: they don't require dynamic symbol binding.
52+
4153
The dynamic linker resolves function symbols when a binary is loaded rather than when each function is first called.
42-
Together with RELRO, this allows relocation tables to be made read-only after loading.
4354
Missing symbols are reported at load time rather than when the affected function is first called.
44-
Static binaries remain static, and Windows and macOS binaries are unaffected.
55+
56+
> [!NOTE]
57+
> [RELRO](https://www.redhat.com/en/blog/hardening-elf-binaries-using-relocation-read-only-relro) protects some relocation-related data from modification after loading.
58+
> The linker marks a memory range for RELRO protection, and the dynamic linker makes that range read-only after applying relocations.
59+
> Go enables RELRO for ELF PIE binaries and shared libraries, including executables built with the Microsoft build of Go [Linux PIE default](#position-independent-executables-on-linux).
60+
>
61+
> Immediate binding extends this protection to the global offset table entries used for function calls.
62+
> Without immediate binding, these entries must remain writable so the dynamic linker can update them when each function is first called.
4563
4664
To restore the upstream linker default for ordinary executables, use:
4765

‎eng/doc/MigrationGuide.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@ The Microsoft build of Go includes [patches](/patches/) that:
4242
- **Disable [GOTOOLCHAIN](https://go.dev/doc/toolchain) by default** to avoid mixups with the official Go distribution.
4343
- **Remove use of undocumented Windows APIs** for compatibility, security, and compliance.
4444
- **Embed Microsoft-specific version information** into built Go binaries for [easier identification](./MicrosoftToolsetIdentification.md).
45-
- **Default to [position-independent executables on Linux](./AdditionalFeatures.md#position-independent-executables-on-linux)** to align with Microsoft's security policies. Starting with Go 1.28, this applies to architectures that support internal PIE linking. These executables require a dynamic loader; use `-buildmode=exe` when a non-PIE executable is needed. Builds using `-race` or `-asan` retain their previous defaults.
46-
- **Enable [immediate binding for ELF binaries](./AdditionalFeatures.md#immediate-binding-for-elf-binaries)** by default starting with Go 1.28 to align with Microsoft's security policies. Dynamic function symbols are resolved at load time rather than on first use; use `-ldflags=-bindnow=false` to opt out.
45+
- **Default to [position-independent executables on Linux with applicable build configurations](./AdditionalFeatures.md#position-independent-executables-on-linux)** starting with Go 1.28.
46+
- **Enable [immediate binding for ELF binaries](./AdditionalFeatures.md#immediate-binding-for-elf-binaries) by default** starting with Go 1.28.
4747

4848
For a detailed description of every feature, see the [Additional Features](./AdditionalFeatures.md) document.
4949

0 commit comments

Comments
 (0)