|
| 1 | +# New Relic CLI Guided Install Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The `newrelic install` command provides an automated, guided installation experience for New Relic agents and integrations. This guide helps you understand when to use guided install and when to use alternative methods. |
| 6 | + |
| 7 | +## Intended Use |
| 8 | + |
| 9 | +### Guided Install is Designed For |
| 10 | + |
| 11 | +The CLI-based guided installation provides a simple, single-command experience for **initial installation on new hosts**: |
| 12 | + |
| 13 | +- Customers who want an easy, automated installation process |
| 14 | +- Standard agent deployments with default configurations |
| 15 | +- Embedding in automated deployment scripts to ensure new servers are monitored from day one |
| 16 | +- Integration with configuration management tools (Ansible, Puppet, Chef) |
| 17 | +- Scenarios where a quick, consistent installation is preferred |
| 18 | + |
| 19 | +Advanced users who require fine-grained control over installation settings, specific version pinning, or custom configuration during installation may prefer manual installation procedures. |
| 20 | + |
| 21 | +### How Guided Install Works |
| 22 | + |
| 23 | +When you run `newrelic install`, the command: |
| 24 | + |
| 25 | +1. Detects your system configuration and running services |
| 26 | +2. Recommends appropriate New Relic agents and integrations |
| 27 | +3. Installs agents with default configuration settings |
| 28 | +4. Validates that agents are reporting data successfully |
| 29 | + |
| 30 | +To ensure a consistent installation experience, the command configures agents with standard default settings. This approach works well for new installations where no prior configuration exists. |
| 31 | + |
| 32 | +## Upgrading Existing Agents |
| 33 | + |
| 34 | +If you have existing New Relic agents with custom configurations that you want to preserve, use the manual upgrade procedures instead: |
| 35 | + |
| 36 | +### Infrastructure Agent Upgrades |
| 37 | + |
| 38 | +For detailed upgrade instructions specific to your operating system, see the New Relic documentation: |
| 39 | + |
| 40 | +**Documentation:** [Update Infrastructure Agent](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/update-or-uninstall/update-infrastructure-agent/) |
| 41 | + |
| 42 | +### APM Agent Upgrades |
| 43 | + |
| 44 | +Each APM agent has specific upgrade procedures that preserve your configurations. See the New Relic documentation for language-specific upgrade instructions: |
| 45 | + |
| 46 | +**Documentation:** [APM Agent Updates](https://docs.newrelic.com/docs/apm/) |
| 47 | + |
| 48 | +## Configuration Considerations |
| 49 | + |
| 50 | +### What Happens to Existing Configurations |
| 51 | + |
| 52 | +If you run `newrelic install` on a system with existing New Relic agents: |
| 53 | + |
| 54 | +- Agent configuration files are set to default values |
| 55 | +- Custom settings (log paths, custom attributes, labels) are not preserved |
| 56 | +- Integration configurations are reset to defaults |
| 57 | + |
| 58 | +This behavior ensures a clean, consistent installation but may not be suitable for systems with custom configurations you want to keep. |
| 59 | + |
| 60 | +### Backing Up Configurations |
| 61 | + |
| 62 | +If you plan to use guided install on a system with existing agents, consider backing up your configuration files first: |
| 63 | + |
| 64 | +**Linux:** |
| 65 | +```bash |
| 66 | +# Back up main config file |
| 67 | +sudo cp /etc/newrelic-infra.yml /etc/newrelic-infra.yml.backup |
| 68 | + |
| 69 | +# Back up integrations directory |
| 70 | +sudo cp -r /etc/newrelic-infra /etc/newrelic-infra.backup |
| 71 | +``` |
| 72 | + |
| 73 | +**Windows:** |
| 74 | +```powershell |
| 75 | +Copy-Item -Path "C:\Program Files\New Relic\newrelic-infra" -Destination "C:\Program Files\New Relic\newrelic-infra.backup" -Recurse |
| 76 | +``` |
| 77 | + |
| 78 | +## Frequently Asked Questions |
| 79 | + |
| 80 | +### Can I use guided install to upgrade my existing agents? |
| 81 | + |
| 82 | +While the command will run successfully, it's designed for new installations. For upgrades that preserve your custom configurations, we recommend using the manual upgrade procedures for your specific agent type. |
| 83 | + |
| 84 | +### Will my telemetry data be affected? |
| 85 | + |
| 86 | +No. Guided install only affects local agent configuration files. Your historical data in New Relic remains unchanged. |
| 87 | + |
| 88 | +### Can I customize the installation? |
| 89 | + |
| 90 | +The guided install uses standard default configurations. For custom setups, you can either: |
| 91 | +1. Use guided install and then manually edit configuration files afterward |
| 92 | +2. Perform a manual installation following agent-specific documentation |
| 93 | + |
| 94 | +### What if I need help? |
| 95 | + |
| 96 | +- **Documentation:** [New Relic Docs](https://docs.newrelic.com/) |
| 97 | +- **Issues and Questions:** [GitHub Issues](https://github.com/newrelic/newrelic-cli/issues) |
| 98 | +- **General Support:** [New Relic Support](https://support.newrelic.com/) |
| 99 | + |
| 100 | +## Command Reference |
| 101 | + |
| 102 | +For complete command options, run: |
| 103 | + |
| 104 | +```bash |
| 105 | +newrelic install --help |
| 106 | +``` |
| 107 | + |
| 108 | +See also: |
| 109 | +- [CLI Documentation](newrelic.md) |
| 110 | +- [Getting Started Guide](GETTING_STARTED.md) |
| 111 | +- [New Relic Infrastructure Agent Documentation](https://docs.newrelic.com/docs/infrastructure/) |
0 commit comments