Docs: Document COMPlus_EnableDiagnostics env var

[ChrisMcKee]

Related to https://github.com/dotnet/coreclr/issues/15243
In order for netcore to run in a readonly container the env var has to be set to zero.
The documentation around this environment variable or in fact around running docker in a secure manner is vague at best.
The reasoning as to why this variable is on by default is non-existent.
I 'believe' it exists in order to provide ETW as per the full framework https://blogs.msdn.microsoft.com/distributedservices/2009/06/19/tracing-in-com-and-complus/ but without disabling a readonly .net container throws a god awful unreadable error.

So for clarity it would be great if the documentation covered this aspect of containerisation and provides the rationale for why this variable and respective code is enabled and what you lose by not having it enabled. (I expect what you lose is nothing in reality as most people are running these containers statelessly within orchestration systems and have no real ties to disk in the first place)

[mairaw]

Thanks for your feedback @ChrisMcKee. @richlander @KathleenDollard any ideas who could help with this?

[RehanSaeed]

It should be noted that setting this environment variables value to zero doesn't actually seem to enable you to run containers in read only mode. I have a full repro at https://github.com/RehanSaeed/ReadOnlyDockerTest. See also https://github.com/aspnet/aspnet-docker/issues/331.

[ChrisMcKee]

Worked for me with a new project.
I'll take a look at your repro in a bit.
I used alpine, not sure what the base image is off the top of my head.

[RehanSaeed]

The Dockerfile in my repro looks like this:

 FROM microsoft/dotnet:2.2-sdk AS builder
 WORKDIR /source
 COPY *.csproj .
 RUN dotnet restore
 COPY . .
 RUN dotnet publish --output /app/ --configuration Release

 FROM microsoft/dotnet:2.2-aspnetcore-runtime
 ENV COMPlus_EnableDiagnostic=0
 WORKDIR /app
 COPY --from=builder /app .
 ENTRYPOINT ["dotnet", "ReadOnlyTest.dll"]

[ChrisMcKee]

Thats... perplexing; I get the same error locally. But if I run a project I know I've already configured...

λ docker run -e CONFIG_FILE=appsettings.development.json --cap-add SYS_PTRACE --rm --read-only -it testproxy:latest
[11:06:57 INF] class=Startup method=ConfigureServices state=Starting
[11:06:57 WRN] Using an in-memory repository. Keys will not be persisted to storage.
[11:06:57 WRN] Neither user profile nor HKLM registry available. Using an ephemeral key repository. Protected data will be unavailable when application exits.
[11:06:57 INF] Creating key {} with creation date 2019-02-11 11:06:57Z, activation date 2019-02-11 11:06:57Z, and expiration date 2019-05-12 11:06:57Z.
[11:06:57 WRN] No XML encryptor configured. Key {} may be persisted to storage in unencrypted form.
[11:06:57 INF] Service Starting
Hosting environment: Production
Content root path: /app
Now listening on: http://0.0.0.0:52193
Application started. Press Ctrl+C to shut down.

I've even altered your repro docker and cs files to closer resemble my working project and it fails...

[RehanSaeed]

What version is your project that worked? Maybe the latest 2.2 is broken again?

[ChrisMcKee]

ReadonlyRepro.zip

ok I've just created a new project via VS; added a the env vars, slightly modified the docker file build (so the shell script I shoved in the route paths properly)

and it works fine.

(if you dont have wsl talking to dockerforwindows you can just paste the command in cmd at the sln level docker build -t readonlyrepro ReadonlyRepro/ && docker run --rm --read-only -it readonlyrepro:latest)

Let me know if that works for you.

[ChrisMcKee]

I've tried breaking the working repro attached previously by diffing with your repro

• Startup.cs adding using Microsoft.AspNetCore.Http; , removing services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); and swapping out the app.UseMvc(); for the app.Run(async (context) => has no effect on readonly mode.

• changing <PackageReference Include="Microsoft.AspNetCore.App" Version="2.2.1" /> to no effect.

I've ran diff over the two slns and other than all of yours being unix line format (which my working sln is but the newly generated code isnt) I can't see any real difference or I'm missing something tiny yet breaking in here 😬

And yep we run 2.2.1

[ChrisMcKee]

@RehanSaeed ok mate I got yours working

I changed the dockerfile to

FROM microsoft/dotnet:2.2-aspnetcore-runtime AS base
WORKDIR /app
EXPOSE 52193

FROM microsoft/dotnet:2.2-sdk AS build
WORKDIR /src
COPY . .
WORKDIR "/src"
RUN dotnet build "ReadOnlyTest.csproj" -c Release -o /app

FROM build AS publish
RUN dotnet publish "ReadOnlyTest.csproj" -c Release -o /app

FROM base AS final
WORKDIR /app
ENV DOTNET_RUNNING_IN_CONTAINER=true
ENV DOTNET_CLI_TELEMETRY_OPTOUT=1
# OPT OUT OF Diagnostic pipeline so we can run readonly.
ENV COMPlus_EnableDiagnostics=0

COPY --from=publish /app .
ENTRYPOINT ["dotnet", "ReadOnlyTest.dll"]

[ChrisMcKee]

Shit.. nailed it

ENV COMPlus_EnableDiagnostic=0 - https://github.com/RehanSaeed/ReadOnlyDockerTest/blob/master/Dockerfile#L10

Missing the S
ENV COMPlus_EnableDiagnostics=0

[ChrisMcKee]

so this replacement for the one in your repo works

FROM microsoft/dotnet:2.2-sdk AS builder
WORKDIR /source
COPY *.csproj .
RUN dotnet restore
COPY . .
RUN dotnet publish --output /app/ --configuration Release

# Stage 2
FROM microsoft/dotnet:2.2-aspnetcore-runtime
ENV COMPlus_EnableDiagnostics=0
WORKDIR /app
COPY --from=builder /app .
ENTRYPOINT ["dotnet", "ReadOnlyTest.dll"]

Typos; the ultimate killer 😉

Just so you know; it's usually a good idea to add ENV DOTNET_CLI_TELEMETRY_OPTOUT=1 unless you want to filter out msft telemetry traffic when debugging.
And you no longer need to restore; build+publish implicitly do it for you.

@RehanSaeed at least that's sorted 😄

[RehanSaeed]

@ChrisMcKee Thanks for your investigation. That typo is not something I'd have spotted.

Perhaps you can update the issue title.

[ChrisMcKee]

@RehanSaeed tbh this issue is about documentation; you just nerd-sniped me with your issue 😉
Totally changing the title 👍