From 29df9bf5affea1c74d9c85b2f77ec644b9447bba Mon Sep 17 00:00:00 2001 From: crandmck Date: Fri, 10 Mar 2017 10:01:00 -0800 Subject: [PATCH 1/5] Add security advisory --- _data/sidebars/lb2_sidebar.yml | 4 ++ _data/sidebars/lb3_sidebar.yml | 9 ++++ pages/en/lb2/Security-advisories.md | 1 + pages/en/lb2/Security-advisory-03-10-2017.md | 45 ++++++++++++++++++++ pages/en/lb3/Security-advisories.md | 23 ++++++++++ pages/en/lb3/Security-advisory-03-10-2017.md | 45 ++++++++++++++++++++ 6 files changed, 127 insertions(+) create mode 100644 pages/en/lb2/Security-advisory-03-10-2017.md create mode 100644 pages/en/lb3/Security-advisories.md create mode 100644 pages/en/lb3/Security-advisory-03-10-2017.md diff --git a/_data/sidebars/lb2_sidebar.yml b/_data/sidebars/lb2_sidebar.yml index 46117464e..8dcf38031 100644 --- a/_data/sidebars/lb2_sidebar.yml +++ b/_data/sidebars/lb2_sidebar.yml @@ -146,6 +146,10 @@ children: output: 'web, pdf' children: + - title: '03-10-2016' + url: /doc/en/lb2/Security-advisory-03-10-2017.html + output: 'web, pdf' + - title: '08-16a-2016' url: /doc/en/lb2/Security-advisory-08-16a-2016.html output: 'web, pdf' diff --git a/_data/sidebars/lb3_sidebar.yml b/_data/sidebars/lb3_sidebar.yml index e1015f652..ab7c18928 100644 --- a/_data/sidebars/lb3_sidebar.yml +++ b/_data/sidebars/lb3_sidebar.yml @@ -123,6 +123,15 @@ children: url: /doc/en/lb3/Tutorials-and-examples.html output: 'web, pdf' +- title: 'Security advisories' + url: /doc/en/lb3/Security-advisories.html + output: 'web, pdf' + children: + + - title: '03-10-2016' + url: /doc/en/lb3/Security-advisory-03-10-2017.html + output: 'web, pdf' + - title: 'Creating an application' url: /doc/en/lb3/Creating-an-application.html output: 'web, pdf' diff --git a/pages/en/lb2/Security-advisories.md b/pages/en/lb2/Security-advisories.md index cfdef2733..fba262a8d 100644 --- a/pages/en/lb2/Security-advisories.md +++ b/pages/en/lb2/Security-advisories.md @@ -13,6 +13,7 @@ summary: These are important advisories about known security issues: +* [Security advisory 03-10-2017](Security-advisory-03-10-2017.html) * [Security advisory 08-16a-2016](Security-advisory-08-16a-2016.html) * [Security advisory 08-16-2016](Security-advisory-08-16-2016.html) * [Security advisory 01-12-2016](Security-advisory-01-12-2016.html) diff --git a/pages/en/lb2/Security-advisory-03-10-2017.md b/pages/en/lb2/Security-advisory-03-10-2017.md new file mode 100644 index 000000000..ee781bdc6 --- /dev/null +++ b/pages/en/lb2/Security-advisory-03-10-2017.md @@ -0,0 +1,45 @@ +--- +title: "Security advisory 03-10-2017" +lang: en +layout: page +toc: false +keywords: LoopBack +tags: security +sidebar: lb2_sidebar +permalink: /doc/en/lb2/Security-advisory-03-10-2017.html +--- +* **Security risk**: Medium-high  +* **Vulnerability**: `loopback-component-storage` to directory traversal attack + +### Description + +A security leak exposing `loopback-component-storage` to directory traversal attack. The component was exposed to a vulnerability where an attacker could use a command to retrieve the content of the `server.js` file of a LoopBack application and crash the server. + +### Reported by + +Pratibha Rikh + +### Versions affected + +loopback-component-storage 3.0.0 and earlier + +### Solution + +Upgrade to loopback-component-storage 3.0.1 or later. + +Ensure that your application's `package.json` has the following line: + +```js +"dependencies": { + ... + "loopback-component-storage": "^3.0.0", + ... + }, +``` + +Then upgrade your project dependencies to use the latest version : + +``` +$ cd +$ npm update +``` diff --git a/pages/en/lb3/Security-advisories.md b/pages/en/lb3/Security-advisories.md new file mode 100644 index 000000000..806cc74f4 --- /dev/null +++ b/pages/en/lb3/Security-advisories.md @@ -0,0 +1,23 @@ +--- +title: "Security advisories" +lang: en +layout: page +toc: false +keywords: LoopBack +tags: +sidebar: lb3_sidebar +permalink: /doc/en/lb3/Security-advisories.html +summary: +--- + +These are important advisories about known security issues: + +* [Security advisory 03-10-2017](Security-advisory-03-10-2017.html) + +{% include important.html content=" +Some advisories may require action on your part, for example to upgrade certain packages. +" %} + +## How to report a security issue + +If you think you have discovered a new security issue with any StrongLoop package, please do not report it on GitHub.  Instead, send an email to [callback@us.ibm.com](mailto:callback@us.ibm.com) with a full description and steps to reproduce. diff --git a/pages/en/lb3/Security-advisory-03-10-2017.md b/pages/en/lb3/Security-advisory-03-10-2017.md new file mode 100644 index 000000000..146d581ae --- /dev/null +++ b/pages/en/lb3/Security-advisory-03-10-2017.md @@ -0,0 +1,45 @@ +--- +title: "Security advisory 03-10-2017" +lang: en +layout: page +toc: false +keywords: LoopBack +tags: security +sidebar: lb3_sidebar +permalink: /doc/en/lb3/Security-advisory-03-10-2017.html +--- +* **Security risk**: Medium-high +* **Vulnerability**: `loopback-component-storage` to directory traversal attack + +### Description + +A security leak exposing `loopback-component-storage` to directory traversal attack. The component was exposed to a vulnerability where an attacker could use a command to retrieve the content of the `server.js` file of a LoopBack application and crash the server. + +### Reported by + +Pratibha Rikh + +### Versions affected + +loopback-component-storage 3.0.0 and earlier + +### Solution + +Upgrade to loopback-component-storage 3.0.1 or later. + +Ensure that your application's `package.json` has the following line: + +```js +"dependencies": { + ... + "loopback-component-storage": "^3.0.0", + ... + }, +``` + +Then upgrade your project dependencies to use the latest version : + +``` +$ cd +$ npm update +``` From 8c6221233241e034d6aca9a03056ae2baf2bbc89 Mon Sep 17 00:00:00 2001 From: crandmck Date: Fri, 10 Mar 2017 16:23:54 -0800 Subject: [PATCH 2/5] Explain how to set db creds via env vars --- pages/en/lb3/Advanced-topics-data-sources.md | 10 +++--- .../lb3/Attaching-models-to-data-sources.md | 31 ++++++++++++++++++- .../lb3/Connecting-models-to-data-sources.md | 21 +++++++------ .../lb3/Environment-specific-configuration.md | 5 +-- pages/en/lb3/datasources.json.md | 24 +++++++------- 5 files changed, 61 insertions(+), 30 deletions(-) diff --git a/pages/en/lb3/Advanced-topics-data-sources.md b/pages/en/lb3/Advanced-topics-data-sources.md index d79d06226..723bf24f1 100644 --- a/pages/en/lb3/Advanced-topics-data-sources.md +++ b/pages/en/lb3/Advanced-topics-data-sources.md @@ -17,12 +17,9 @@ The diagram illustrates the relationship between LoopBack `Model`, `DataSource 1. Define the model. -2. Create an instance of `ModelBuilder` or `DataSource`. `DataSource` extends from `ModelBuilder`. - ModelBuilder is responsible for compiling model definitions to JavaScript constructors representing model classes. - DataSource inherits that function from ModelBuilder. +2. Create an instance of `ModelBuilder` or `DataSource`. `DataSource` extends from `ModelBuilder`. `ModelBuilder` is responsible for compiling model definitions to JavaScript constructors representing model classes. `DataSource` inherits that function from ModelBuilder. -3. Use `ModelBuilder` or `DataSource` to build a JavaScript constructor (i.e. the model class) from the model definition. - Model classes built from `ModelBuilder` can be later attached to a DataSource to receive the mixin of data access functions. +3. Use `ModelBuilder` or `DataSource` to build a JavaScript constructor (i.e. the model class) from the model definition. Model classes built from `ModelBuilder` can be later attached to a DataSource to receive the mixin of data access functions. 4. As part of step 2, `DataSource` initializes the underlying `Connector` with a settings object which provides configurations to the connector instance.  `Connector` collaborates with `DataSource` to define the functions as `DataAccessObject` to be mixed into the model class. @@ -35,6 +32,9 @@ It's a factory for data access logic around model classes. With the ability to p ## Creating a DataSource programmatically +{% include warning.html content="Don't put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) +"%} + The [`DataSource` constructor](http://apidocs.strongloop.com/loopback-datasource-juggler/#datasource) accepts the following arguments: * name: Optional name of the data source instance being created.  diff --git a/pages/en/lb3/Attaching-models-to-data-sources.md b/pages/en/lb3/Attaching-models-to-data-sources.md index 272b0013d..a2238cac4 100644 --- a/pages/en/lb3/Attaching-models-to-data-sources.md +++ b/pages/en/lb3/Attaching-models-to-data-sources.md @@ -56,7 +56,11 @@ The tool will then add an entry such as the following to `datasources.json`: This example creates a MySQL data source called "corp1". The identifier determines the name by which you refer to the data source and can be any string. -## Add data source credentials +## Add database credentials + +{% include tip.html content="Putting production database credentials in a JSON file is not recommended for security reasons. +Instead, create the data source programmatically and load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). +"%} Edit `datasources.json` to add the necessary authentication credentials for the data source; typically hostname, username, password, and database name. @@ -74,6 +78,31 @@ For example: } ``` +### Specifying database credentials with environment variables + +Best practice is not to put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, define datasources in a JavaScript file then load the values from environment variables. + +For example, assuming you have set a valid MongoDB username and password in the +environment variables MONGO_USER and MONGO_PASS, respectively: + +{% include code-caption.html content="datasources.production.js" %} +```javascript +var DataSource = require('loopback-datasource-juggler').DataSource; + +var dataSource = new DataSource({ + connector: require('loopback-connector-mongodb'), + host: 'localhost', + port: 27017, + database: 'mydb', + username: process.env.MONGO_USER, + password: process.env.MONGO_PASS +}); + ``` + +You can use different credentials for development and production by using the NODE_ENV +environment variable, as explained in [Environment-specific configuration](Environment-specific-configuration.html#data-source-configuration). + + ## Make the model use the data source When you create a new model with the [model generator](Model-generator.html), diff --git a/pages/en/lb3/Connecting-models-to-data-sources.md b/pages/en/lb3/Connecting-models-to-data-sources.md index ad5af8cbd..858a49645 100644 --- a/pages/en/lb3/Connecting-models-to-data-sources.md +++ b/pages/en/lb3/Connecting-models-to-data-sources.md @@ -11,7 +11,7 @@ summary: ## Overview -{% include image.html file="9830484.png" alt="" %}  +{% include image.html file="9830484.png" alt="Models, data sources, and connectors" %}  LoopBack models connect to backend systems such as databases via _data sources_ that provide create, retrieve, update, and delete (CRUD) functions. LoopBack also generalizes other backend services, such as REST APIs, SOAP web services, and storage services, and so on, as data sources. @@ -66,6 +66,9 @@ To connect a model to a data source, follow these steps: For information on the properties that each connector supports, see documentation for the specific connector under [Connectors reference](Connectors-reference). + {% include warning.html content="Don't put production database credentials in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) + "%} + 3. Install the corresponding connector as a dependency of your app with `npm`. For example:  @@ -274,17 +277,18 @@ However, data sources for database connectors (Oracle, MySQL, PostgreSQL, MongoD as described in the following table. - + - - + + + + - - diff --git a/pages/en/lb3/Environment-specific-configuration.md b/pages/en/lb3/Environment-specific-configuration.md index ffc024e5c..5af39e660 100644 --- a/pages/en/lb3/Environment-specific-configuration.md +++ b/pages/en/lb3/Environment-specific-configuration.md @@ -166,9 +166,6 @@ Example data sources: {% include code-caption.html content="datasources.json" %} ```javascript { - // the key is the datasource name - // the value is the config object to pass to - // app.dataSource(name, config). db: { connector: 'memory' } @@ -207,7 +204,7 @@ the datasource. ## Getting values from environment variables -You can easily set an environment variable when you run an application. The command you use depends on your operating system. +You can easily get the value of an environment variable in an application. The command you use depends on your operating system. ### MacOS and Linux diff --git a/pages/en/lb3/datasources.json.md b/pages/en/lb3/datasources.json.md index 068533c45..e0cb2ea2f 100644 --- a/pages/en/lb3/datasources.json.md +++ b/pages/en/lb3/datasources.json.md @@ -33,22 +33,23 @@ For example: } ``` -To access data sources in application code, use `app.datasources._datasourceName_`. +To access data sources in application code, use app.datasources.datasourceName. ## Standard properties All data sources support a few standard properties. Beyond that, specific properties and defaults depend on the connector being used.
PropertyTypePropertyType Description
connector String -

Connector name; for example:

+
Connector name; for example:
  • "memory"
  • "loopback-connector-mongodb" or "mongodb"
  • @@ -324,9 +328,8 @@ as described in the following table.
url String -

Combines and overrides host, port, user, password, and database properties.

-

Only valid with MongoDB connector, PostgreSQL connector, and SQL Server connector.

+
Combines and overrides host, port, user, password, and database properties. + Only valid with certain connectors; see connector documentation.
- + + + - @@ -112,6 +112,9 @@ To connect a model to a data source, follow these steps: For information on the properties that each connector supports, see the specific connector documentation in [Database connectors](Database-connectors.html). + {% include warning.html content="Don't put production database credentials in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) + "%} + 3. Install the corresponding connector as a dependency of your app with `npm`, for example:  ```shell @@ -159,7 +162,7 @@ See [Creating models](Creating-models.html) for more information. You can override values set in `datasources.json` in the following files: * `datasources.local.js` or `datasources.local.json` -* `datasources._env_.js` or `datasources._env_.json`, where _`env`_ is the value of `NODE_ENV` environment variable (typically `development` or `production`). +* datasources.env.js or datasources.env.json, where env is the value of `NODE_ENV` environment variable (typically `development` or `production`). For example, `datasources.production.json`. {% include important.html content=" @@ -168,12 +171,11 @@ The additional files can override the top-level data-source options with string Example data sources: +In the JSON, the key is the datasource name and the value is the configuration object to pass to `app.dataSource(name, config)`. + {% include code-caption.html content="datasources.json" %} ```javascript { - // the key is the datasource name - // the value is the config object to pass to - // app.dataSource(name, config). db: { connector: 'memory' } From 9e1732be9bd7d2f3438c4b79e293b9af2af5a3ed Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 15 Mar 2017 14:48:36 -0700 Subject: [PATCH 3/5] Clean up table --- pages/en/lb2/Basic-model-object.md | 31 ++++++++++++------------------ 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/pages/en/lb2/Basic-model-object.md b/pages/en/lb2/Basic-model-object.md index cbed32e2e..1c17abdb2 100644 --- a/pages/en/lb2/Basic-model-object.md +++ b/pages/en/lb2/Basic-model-object.md @@ -22,8 +22,7 @@ the [RelationMixin object](http://apidocs.strongloop.com/loopback-datasource-ju ## Events -{% include important.html content=" -The following events are deprecated in favor of [operation hooks](Operation-hooks.html): +{% include note.html content="The following events are deprecated in favor of [operation hooks](Operation-hooks.html): * changed * deleted @@ -31,25 +30,23 @@ The following events are deprecated in favor of [operation hooks](Operation-hook " %} The following table summarizes the events that LoopBack models can emit. +For more information, see [Events](Events.html).
Property Description
connector -

LoopBack connector to use; one of:

+
LoopBack connector to use:
  • memory
  • loopback-connector-oracle or just "oracle"
  • @@ -57,10 +58,9 @@ All data sources support a few standard properties. Beyond that, specific proper
  • loopback-connector-postgresql or just "postgresql"
  • loopback-connector-soap or just "soap"
  • loopback-connector-mssql or just "mssql"
  • -
  • -

    loopback-connector-rest or just "rest"

    -
  • +
  • loopback-connector-rest or just "rest"
  • loopback-storage-service
  • +
  • Another LoopBack data source connector
- + - - + + - + + + - @@ -62,11 +59,8 @@ The following table summarizes the events that LoopBack models can emit. - @@ -75,8 +69,7 @@ The following table summarizes the events that LoopBack models can emit. - From 7bdcac06ff44d0d7c504906d8d39022982978e0c Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 15 Mar 2017 15:19:16 -0700 Subject: [PATCH 4/5] Update per Miroslav's comments --- .../lb3/Attaching-models-to-data-sources.md | 45 ++++++++++++------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/pages/en/lb3/Attaching-models-to-data-sources.md b/pages/en/lb3/Attaching-models-to-data-sources.md index a2238cac4..792b3a9d6 100644 --- a/pages/en/lb3/Attaching-models-to-data-sources.md +++ b/pages/en/lb3/Attaching-models-to-data-sources.md @@ -59,7 +59,7 @@ This example creates a MySQL data source called "corp1". The identifier determin ## Add database credentials {% include tip.html content="Putting production database credentials in a JSON file is not recommended for security reasons. -Instead, create the data source programmatically and load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). +Instead, load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). "%} Edit `datasources.json` to add the necessary authentication credentials for the data source; typically hostname, username, password, and database name. @@ -80,28 +80,41 @@ For example: ### Specifying database credentials with environment variables -Best practice is not to put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, define datasources in a JavaScript file then load the values from environment variables. +Best practice is not to put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, define the values in environment variables and reference them in the data source configuration file. For example, assuming you have set a valid MongoDB username and password in the environment variables MONGO_USER and MONGO_PASS, respectively: -{% include code-caption.html content="datasources.production.js" %} +{% include code-caption.html content="datasources.json" %} ```javascript -var DataSource = require('loopback-datasource-juggler').DataSource; - -var dataSource = new DataSource({ - connector: require('loopback-connector-mongodb'), - host: 'localhost', - port: 27017, - database: 'mydb', - username: process.env.MONGO_USER, - password: process.env.MONGO_PASS -}); +{ + "db": { + "username": "${MONGO_USER}", + "password": "${MONGO_PASS}" + } +} ``` -You can use different credentials for development and production by using the NODE_ENV -environment variable, as explained in [Environment-specific configuration](Environment-specific-configuration.html#data-source-configuration). - +You can use different credentials for development and production by using the NODE_ENV +environment variable, as explained in [Environment-specific configuration](Environment-specific-configuration.html#data-source-configuration), +for example `datasources.production.json` for production environment when NODE_ENV is 'production'. + +{% include note.html content="LooopBack merges configurations environment-specific configuration (for example in `datasources.production.json`) with the baseline configuration in `datasources.json`. As a result, it's difficult to clear extra settings in environment-specific files, so best practice is to use the single `url` connection string setting (where available) that overrides the other settings. See the example below. +" %} + +{% include code-caption.html content="datasources.json" %} +```js +{ + "db": { + "connector": "mongodb", + "url": "${MONGODB_URL}", + // configuration below is for Development/Test environments only + "host": "localhost", + "database": "my-database-name", + ... + } +} +``` ## Make the model use the data source From e119aed36e833b54999dcc3d637aa0b610c0a557 Mon Sep 17 00:00:00 2001 From: crandmck Date: Tue, 21 Mar 2017 16:21:34 -0700 Subject: [PATCH 5/5] Incorporate comments and general cleanup --- .../lb3/Attaching-models-to-data-sources.md | 44 ++-- .../lb3/Environment-specific-configuration.md | 15 +- pages/en/lb3/datasources.json.md | 191 ++++++------------ 3 files changed, 100 insertions(+), 150 deletions(-) diff --git a/pages/en/lb3/Attaching-models-to-data-sources.md b/pages/en/lb3/Attaching-models-to-data-sources.md index 792b3a9d6..0b83f45e3 100644 --- a/pages/en/lb3/Attaching-models-to-data-sources.md +++ b/pages/en/lb3/Attaching-models-to-data-sources.md @@ -41,27 +41,23 @@ $ apic create --type datasource You can also add and modify data sources using the API Designer tool. -The tool will prompt you for the name of the new data source and the connector to use; for example, MySQL, Oracle, REST, and so on. +The tool will prompt you for the name of the new data source and the connector to use; for example, MongoDB, MySQL, Oracle, REST, and so on. The tool will then add an entry such as the following to `datasources.json`: {% include code-caption.html content="/server/datasources.json" %} ```javascript ... "corp1": { - "name": "corp1", - "connector": "mysql" + "name": "mongo1", + "connector": "mongodb" } ... ``` -This example creates a MySQL data source called "corp1". The identifier determines the name by which you refer to the data source and can be any string. +This example creates a MongoDB data source called "mongo1". The identifier determines the name by which you refer to the data source and can be any string. ## Add database credentials -{% include tip.html content="Putting production database credentials in a JSON file is not recommended for security reasons. -Instead, load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). -"%} - Edit `datasources.json` to add the necessary authentication credentials for the data source; typically hostname, username, password, and database name. For example: @@ -70,14 +66,18 @@ For example: ```javascript "corp1": { "name": "corp1", - "connector": "mysql", - "host": "your-mysql-server.foo.com", + "connector": "mongodb", + "host": "your-mongodb-server.foo.com", "user": "db-username", "password": "db-password", "database": "your-db-name" } ``` +{% include warning.html content="Putting production database credentials in a JSON file is not recommended for security reasons. +Instead, load the credentials from environment variables, as explained [below](#specifying-database-credentials-with-environment-variables). +"%} + ### Specifying database credentials with environment variables Best practice is not to put production database credentials explicitly in JSON or JavaScript files, where they could be a security vulnerability. Instead, define the values in environment variables and reference them in the data source configuration file. @@ -87,28 +87,38 @@ environment variables MONGO_USER and MONGO_PASS, respectively: {% include code-caption.html content="datasources.json" %} ```javascript -{ - "db": { + ... + "accountDS": { + "name": "accountDS", + "connector": "mongodb", + "host": "demo.strongloop.com", + "port": 27017, + "database": "demo", "username": "${MONGO_USER}", "password": "${MONGO_PASS}" } -} + ... ``` -You can use different credentials for development and production by using the NODE_ENV +You can use different data source definitions (including database credentials) for development and production by using the NODE_ENV environment variable, as explained in [Environment-specific configuration](Environment-specific-configuration.html#data-source-configuration), for example `datasources.production.json` for production environment when NODE_ENV is 'production'. -{% include note.html content="LooopBack merges configurations environment-specific configuration (for example in `datasources.production.json`) with the baseline configuration in `datasources.json`. As a result, it's difficult to clear extra settings in environment-specific files, so best practice is to use the single `url` connection string setting (where available) that overrides the other settings. See the example below. -" %} +### Using multiple data source configurations + +LoopBack merges environment-specific configurations (for example in `datasources.production.json`) with the baseline configuration in `datasources.json`. +Environment-specific configurations can override the top-level values with string and number values only. You cannot use objects or array values. + +It can be difficult to clear extra datasource settings inherited from the top-level `datasources.json` file in environment-specific files. To avoid issues, use a single `datasources.json` file that includes both individual settings such as `host`, `port`, and `database` for local environment and a `url` connection string setting that overrides the other settings for staging and production. For example: {% include code-caption.html content="datasources.json" %} ```js { "db": { "connector": "mongodb", + // The url setting will be used only when MONGODB_URL env var is defined "url": "${MONGODB_URL}", - // configuration below is for Development/Test environments only + // configuration below is for development/staging environments only "host": "localhost", "database": "my-database-name", ... diff --git a/pages/en/lb3/Environment-specific-configuration.md b/pages/en/lb3/Environment-specific-configuration.md index 5af39e660..a6a447158 100644 --- a/pages/en/lb3/Environment-specific-configuration.md +++ b/pages/en/lb3/Environment-specific-configuration.md @@ -54,21 +54,21 @@ The value set by the file with the highest priority will always take effect. The 3. **Default configuration file**; for example, `server/config.json`. " %} -Here are some examples of the application configuration files: +Examples of the application configuration files: * [config.json](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/config.json) * [config.local.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/config.local.js) -Here are some examples of data source configuration files: +Examples of data source configuration files: * [datasources.json](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.json) * [datasources.production.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.production.js) * [datasources.staging.js](https://github.com/strongloop/loopback-example-full-stack/blob/master/server/datasources.staging.js) -Here are some examples of the middleware configuration files, the `server/middleware{._env_}.json` file: +Examples of the middleware configuration files: * [middleware.json](middleware.json.html) -* middleware.production.json +* [middleware.development.json](middleware.development.json.html) For an example application, see [https://github.com/strongloop/loopback-example-full-stack/tree/master/server](https://github.com/strongloop/loopback-example-full-stack/tree/master/server). @@ -157,8 +157,7 @@ You can override values set in `datasources.json` in the following files: * datasources.env.js or datasources.env.json, where _`env`_ is the value of `NODE_ENV` environment variable (typically `development` or `production`). For example, `datasources.production.json`. -{% include important.html content=" -The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. +{% include important.html content="The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. " %} Example data sources: @@ -184,9 +183,9 @@ Example data sources: } ``` -You can also configure your datasource._\_env\__.js file to use environment variables: +You can also configure your datasource.env.js file to use environment variables: -{% include code-caption.html content="datasources.production.json" %} +{% include code-caption.html content="datasources.production.js" %} ```javascript module.exports = { db: { diff --git a/pages/en/lb3/datasources.json.md b/pages/en/lb3/datasources.json.md index e0cb2ea2f..ba6937b67 100644 --- a/pages/en/lb3/datasources.json.md +++ b/pages/en/lb3/datasources.json.md @@ -6,12 +6,13 @@ keywords: LoopBack tags: sidebar: lb3_sidebar permalink: /doc/en/lb3/datasources.json.html -summary: +summary: Configure data sources in datasources.json. --- ## Overview -Configure data sources in `/server/datasources.json`. You can set up as many data sources as you want in this file. +Configure data sources in `/server/datasources.json`. You can set up as many data sources as you want in this file. The easiest way to set up a new data source is to use the [data source generator](Data-source-generator.html), which will prompt your for all the +appropriate settings, add them to `/server/datasources.json`, and then install the connector from npm. For example: @@ -21,8 +22,8 @@ For example: "name": "db", "connector": "memory" }, - "myDB": { - "name": "myDB", + "mySQLdb": { + "name": "mySQLdb", "connector": "mysql", "host": "demo.strongloop.com", "port": 3306, @@ -71,125 +72,65 @@ All data sources support a few standard properties. Beyond that, specific proper
EventEmitted when...EventEmitted when... Arguments Argument type Class methods that emitInstance methods that emitInstance methods that emit
'attached' -

Model is attached to an app.

-
-

 

-
-


+
Model is attached to an app. Model class ObjectModel class Object   -
    -
  • DataSource.prototype.createModel
  • -
  • DataSource.prototype.define
  • -
+
DataSource.prototype
.createModel +
DataSource.prototype
.define
Model instance Object   -

Model.prototype.setAttributes()

+
Model.prototype
.setAttributes()
-## Properties for database connectors - -To connect a model to a data source, follow these steps: - -1. Use the [data source generator](Data-source-generator.html) to create a new data source. For example:  -
- ```shell - $ apic create --type datasource - ? Enter the data-source name: mysql-corp - ? Select the connector for mysql: MySQL (supported by StrongLoop) - ``` -
- ```shell - $ lb datasource - ? Enter the data-source name: mysql-corp - ? Select the connector for mysql: MySQL (supported by StrongLoop) - ``` - - Follow the prompts to name the datasource and select the connector to use. - This adds the new data source to `datasources.json` - -2. Edit `server/datasources.json` to add the necessary authentication credentials: typically hostname, username, password, and database name. - - For example: - - **server/datasources.json** - - ```javascript - "mysql-corp": { - "name": "mysql-corp", - "connector": "mysql", - "host": "your-mysql-server.foo.com", - "user": "db-username", - "password": "db-password", - "database": "your-db-name" - } - ``` - - For information on the properties that each connector supports, see - the specific connector documentation in [Database connectors](Database-connectors.html). - - {% include warning.html content="Don't put production database credentials in JSON or JavaScript files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) - "%} - -3. Install the corresponding connector as a dependency of your app with `npm`, for example:  - - ```shell - $ cd - $ npm install --save loopback-connector-mysql - ``` - - See [Connectors](Connecting-models-to-data-sources.html) for the list of connectors. - -4. Use the [model generator](Using-the-model-generator.html) to create a model. -
- ``` - $ apic create --type model - ? Enter the model name: myModel - ? Select the data-source to attach myModel to: mysql (mysql) - ? Select model's base class: PersistedModel - ? Expose myModel via the REST API? Yes - ? Custom plural form (used to build REST URL): - Let's add some test2 properties now. - ... - ``` -
- ``` - $ lb model - ? Enter the model name: myModel - ? Select the data-source to attach myModel to: mysql (mysql) - ? Select model's base class: PersistedModel - ? Expose myModel via the REST API? Yes - ? Custom plural form (used to build REST URL): - Let's add some test2 properties now. - ... - ``` - - When prompted for the data source to attach to, select the one you just created.  - -{% include note.html content=" -The model generator lists the [memory connector](Memory-connector.html), \"no data source,\" and data sources listed in `datasources.json`. That's why you created the data source first in step 1. -" %} - -You can also create models from an existing database. -See [Creating models](Creating-models.html) for more information. - -## Environment-specific configuration - -You can override values set in `datasources.json` in the following files: - -* `datasources.local.js` or `datasources.local.json` -* datasources.env.js or datasources.env.json, where env is the value of `NODE_ENV` environment variable (typically `development` or `production`). - For example, `datasources.production.json`. - -{% include important.html content=" -The additional files can override the top-level data-source options with string and number values only. You cannot use objects or array values. -" %} - -Example data sources: - -In the JSON, the key is the datasource name and the value is the configuration object to pass to `app.dataSource(name, config)`. - -{% include code-caption.html content="datasources.json" %} -```javascript -{ - db: { - connector: 'memory' - } -} -``` +## Database connector properties -{% include code-caption.html content="datasources.production.json" %} -```javascript -{ - db: { - connector: 'mongodb', - database: 'myapp', - user: 'myapp', - password: 'secret' - } -} -``` +Although each data source connector has a different set of properties, +database connectors typically have properties that include +properties for the database server and credentials to log in to it. + +For information on the properties that each connector supports, see +the specific connector documentation in [Database connectors](Database-connectors.html). + +{% include warning.html content="Don't put production database credentials in configuration files, where they could be a security vulnerability. Instead, load the values from environment variables. For more information, see [Specifying database credentials with environment variables](Attaching-models-to-data-sources.html#specifying-database-credentials-with-environment-variables) +"%} + +The following table list common properties that most database connectors provide. +See documentation for the specific connector for full details. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
databaseStringDatabase name
hostStringDatabase host name
passwordStringPassword to connect to database
portNumberDatabase TCP port
urlStringConnection URL that overrides other connection settings.
usernameStringUsername to connect to database