Subzero: More documentation for the NACLENV arg passthrough mechanism.

src/IceBrowserCompileServer.cpp

 //===- subzero/src/IceBrowserCompileServer.cpp - Browser compile server ---===//
 //
 //                        The Subzero Code Generator
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 ///
 /// \file
@@ skipping 35 matching lines @@
   size_t QueryResult =
       nacl_interface_query(NACL_IRT_PRIVATE_PNACL_TRANSLATOR_COMPILE_v0_1,
                            &gIRTFuncs, sizeof(gIRTFuncs));
   if (QueryResult != sizeof(gIRTFuncs))
     llvm::report_fatal_error("Failed to get translator compile IRT interface");
 }
 
 // Allow pnacl-sz arguments to be supplied externally, instead of coming from
 // the browser.  This is meant to be used for debugging.
 //
+// NOTE: This functionality is only enabled in non-MINIMAL Subzero builds, for
+// security/safety reasons.
+//
 // If the SZARGFILE environment variable is set to a file name, arguments are
 // read from that file, one argument per line.  This requires setting 3
 // environment variables before starting the browser:
 //
 // NACL_ENV_PASSTHROUGH=NACL_DANGEROUS_ENABLE_FILE_ACCESS,NACLENV_SZARGFILE
 // NACL_DANGEROUS_ENABLE_FILE_ACCESS=1
 // NACLENV_SZARGFILE=/path/to/myargs.txt
 //
 // In addition, Chrome needs to be launched with the "--no-sandbox" argument.
 //
 // If the SZARGLIST environment variable is set, arguments are extracted from
 // that variable's value, separated by the '|' character (being careful to
 // escape/quote special shell characters).  This requires setting 2 environment
 // variables before starting the browser:
 //
 // NACL_ENV_PASSTHROUGH=NACLENV_SZARGLIST
 // NACLENV_SZARGLIST=arg
 //
 // This does not require the "--no-sandbox" argument, and is therefore much
 // safer, but does require restarting the browser to change the arguments.
 //
 // If external arguments are supplied, the browser's NumThreads specification is
 // ignored, to allow -threads to be specified as an external argument.  Note
 // that the browser normally supplies the "-O2" argument, so externally supplied
 // arguments might want to provide an explicit -O argument.
+//
+// See Chrome's src/components/nacl/zygote/nacl_fork_delegate_linux.cc for the
+// NACL_ENV_PASSTHROUGH mechanism.
+//
+// See NaCl's src/trusted/service_runtime/env_cleanser.c for the NACLENV_
+// mechanism.
 std::vector<std::string> getExternalArgs() {
   std::vector<std::string> ExternalArgs;
   if (BuildDefs::minimal())
     return ExternalArgs;
   char ArgsFileVar[] = "SZARGFILE";
   char ArgsListVar[] = "SZARGLIST";
   if (const char *ArgsFilename = getenv(ArgsFileVar)) {
     std::ifstream ArgsStream(ArgsFilename);
     std::string Arg;
     while (ArgsStream >> std::ws, std::getline(ArgsStream, Arg)) {
@@ skipping 230 matching lines @@
   llvm::report_fatal_error("no browser hookups");
 }
 
 ErrorCode &BrowserCompileServer::getErrorCode() {
   llvm::report_fatal_error("no browser hookups");
 }
 
 } // end of namespace Ice
 
 #endif // PNACL_BROWSER_TRANSLATOR