From baa20c572cffec2b508e5d0cd4194e39303441ae Mon Sep 17 00:00:00 2001 From: Cheryl Potter Date: Thu, 12 May 2016 14:27:00 -0700 Subject: [PATCH] docs: Add Emulator Console authentication feature Change-Id: I77c36a71a208714443e09b10caf5e35141afca95 --- docs/html/tools/help/emulator.jd | 103 +++++++++++++++++++++++++---- docs/html/tools/sdk/tools-notes.jd | 36 +++++++++- 2 files changed, 124 insertions(+), 15 deletions(-) diff --git a/docs/html/tools/help/emulator.jd b/docs/html/tools/help/emulator.jd index 08e3f6f345980..5ff3367cfc5f4 100644 --- a/docs/html/tools/help/emulator.jd +++ b/docs/html/tools/help/emulator.jd @@ -42,6 +42,7 @@ page.title=Using Android Emulator Command-Line Features
  • Using the Emulator Console
      +
    1. Starting and Stopping a Console Session
    2. Port Redirection
    3. Geo Location Provider Emulation
    4. Hardware Events Emulation
      5. @@ -1440,32 +1441,106 @@ from one of the emulators.

      Each running emulator instance provides a console that lets you query and control the emulated device environment. For example, you can use the console to manage port redirection, network -characteristics, and telephony events while your application is running on the emulator. To -access the console and enter commands, use telnet to connect to the console's port number.

      +characteristics, and telephony events while your application is running on the emulator. -

      To connect to the console of any running emulator instance at any time, use this command:

      +

      Starting and Stopping a Console Session

      +

      To access the console and enter commands, from a terminal window, use telnet to +connect to the +console port and provide your authentication token.

      -
      telnet localhost <console-port>
      -

      An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port. -The port numbers differ by 1, with the {@code adb} port having the higher port number. The console -of the first emulator instance running on a given machine uses console port 5554 and {@code adb} +

      To connect to the console of a running emulator instance:

      + +
        +
      1. Open a terminal window and enter the following command:
        2. + +
        telnet localhost console-port
        + +

        An emulator instance occupies a pair of adjacent ports: a console port and an adb port. +The port numbers differ by 1, with the adb port having the higher port number. The console +of the first emulator instance running on a particular machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility.

        -

        To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:

        +

        To connect to the emulator console, you must specify a valid console port. If multiple emulator + instances are running, you need to determine the console port of the emulator instance you want + to connect to. The emulator window title lists the console port number. For example, the + window title for an emulator using console port 5554 + could be 5554:Nexus_5X_API_23.

        -

        Android Emulator (5554)

        +

        Alternatively, you can use the adb devices command, which prints a list of + running emulator instances and their console port numbers. For more information, see + Querying for Emulator/Device Instances. +

        -

        Alternatively, you can use the adb devices command, which prints a list of running emulator instances and their console port numbers. For more information, see Querying for Emulator/Device Instances in the adb documentation.

        +

        Note: The emulator listens for connections on ports 5554 to 5587 and accepts + connections from localhost only.

        -

        Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.

        +
      2. After the console displays OK, enter the auth +auth_token command.
        3. -

        Once you are connected to the console, you can then enter help [command] to see a list of console commands and learn about specific commands.

        +

        Before you can enter console commands, the emulator console requires authentication. + auth_token must + match the contents of the .emulator_console_auth_token file in your home directory. +

        -

        To exit the console session, use quit or exit.

        +

        If that file doesn't exist, the telnet localhost console-port + command creates the file, which contains a randomly generated authentication token.

        -

        The following sections below describe the major functional areas of the console.

        +

        To disable authentication, delete the token from the + .emulator_console_auth_token file or create an empty file if it doesn't exist.

        + +
      3. After you're connected to the console, enter console commands.
        4. + +

        Enter help and help command to see a + list of console commands and learn about specific commands.

        + +
      4. To exit the console session, enter quit or exit.
        5. +
      + +

      Here's an example session:

      + +
      +me-macbook$ telnet localhost 5554
+Trying ::1...
+telnet: connect to address ::1: Connection refused
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+Android Console: Authentication required
+Android Console: type 'auth <auth_token>' to authenticate
+Android Console: you can find your <auth_token> in
+'/Users/me/.emulator_console_auth_token'
+OK
+auth 123456789ABCdefZ
+Android Console: type 'help' for a list of commands
+OK
+help
+Android console command help:
+
+    help|h|?         print a list of commands
+    crash            crash the emulator instance
+    kill             kill the emulator instance
+    quit|exit        quit control session
+    redir            manage port redirections
+    power            power related commands
+    event            simulate hardware events
+    avd              control virtual device execution
+    finger           manage emulator fingerprint
+    geo              Geo-location commands
+    sms              SMS related commands
+    cdma             CDMA related commands
+    gsm              GSM related commands
+    rotate           rotate the screen by 90 degrees
+
+try 'help <command>' for command-specific help
+OK
+exit
+Connection closed by foreign host.
+me-macbook$
+
      + +

      The following sections describe the major functional areas of the console.

      Port Redirection

      diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd index f72d3f3e943f1..ac1f4ce1c3aea 100644 --- a/docs/html/tools/sdk/tools-notes.jd +++ b/docs/html/tools/sdk/tools-notes.jd @@ -25,9 +25,43 @@ Tools you are using, refer to the "Installed Packages" listing in the Android SD

      +

      + SDK Tools, Revision 25.1.6 (May 2016) +

      + +
      + +
      +
      Dependencies:
      + +
      +
        +
      • Android SDK Platform-tools revision 23 or later.
        • +
      +
      + +
      General Notes:
      +
      +
        +
      • The Android Emulator Console now requires + authentication + before you can enter commands. Enter the auth auth_token command after + you telnet to an emulator instance. auth_token must + match the contents of the .emulator_console_auth_token file in your + home directory. +
        • +
      +
      + +
      +
      + + +

      SDK Tools, Revision 25.0.0 (April 2016)