Update readme

README.md

@@ -3,16 +3,15 @@ A Go broker for MSSQL Service
 
 ## Summary
 
-The cf-mssql-broker project implements and exposes the CF (Cloud Foundy) Service Broker API (http://docs.cloudfoundry.org/services/api.html) to facilitate the managemnt of a single Microsoft SQL Server instance. The minimum version supported is SQL Server 2012 Express.
+The cf-mssql-broker project implements and exposes the CF (Cloud Foundy) [Service Broker API](http://docs.cloudfoundry.org/services/api.html) to facilitate the managemnt of a single Microsoft SQL Server instance. The minimum version supported is SQL Server 2012 Express.
 
-For the provision operation of a CF service instance the broker will create a contained database (https://msdn.microsoft.com/en-us/library/ff929071.aspx) on the targeted SQL Server.
+For the provision operation of a CF service instance the broker will create a [contained database](https://msdn.microsoft.com/en-us/library/ff929071.aspx) on the targeted SQL Server.
 
 For the binding operation the broker will create an SQL Server user and a ramdomly genrated password in the contained database of the CF service instance.
 
 The broker serive does not need to have save any state, thus it can be farmed or deployed on another box without any data migration. To keep track of provisioned instances and bindings it will use the IDs from Service Broker API in the database name and in the SQL Server user name.
 
 
-
 ## SQL Server config
 
 ### Enable TCP access for SQL Server
@@ -23,15 +22,18 @@ Use the sql management studio to enable tcp or use the following doc to automate
 
 To configure or automate the firewall for SQL Server use the following PS example:
 
+```sh
 New-NetFirewallRule -DisplayName “SQL Server” -Direction Inbound –Protocol TCP –LocalPort 1433 -Action allow
+```
 
 
 ### Enable Contained Database Authentication
 
-Binding operations will create a user with a password only in the contained database. This is disabled by 
-default in SQL Server 2012 and 2014. Use the following commmand to enable contained database authentication:
+Binding operations will create a user with a password only in the contained database. This is disabled by default in SQL Server 2012 and 2014. Use the following commmand to enable contained database authentication:
 
+```sh
 SQLCmd -S .\sqlexpress  -Q "EXEC sp_configure 'contained database authentication', 1; reconfigure;"
+```
 
 ### Tips and Tricks
 
@@ -40,59 +42,75 @@ choco install mssqlserver2012express
 
 ## Configuration
 
-cf_mssql_broker_config.json is the default configuration file. The config file can be overridden with
-the following flag: -config=/new/path/config.json
+cf_mssql_broker_config.json is the default configuration file. The config file can be overridden with the following flag: -config=/new/path/config.json
+
+The `servedMssqlBindingHostname` and `servedMssqlBindingPort` properties need to be changed for every installetion. They are the hostname and port that are sent to the CF applications, and need to be accessible from the CF application network. NOTE: Do not change this value on a existing mssql broker with active bindings. If this is necessary, extra migrations steps need to be taken for the exsing bindings in the CF's Cloud Controller.
 
-The servedMssqlBindingHostname and servedMssqlBindingPort need to be changed for every installetion.
-They are the hostname and port that are sent to the CF applicatoins, and need to be accessible from the CF application network. NOTE: Do not change this value on a existing mssql broker with active bindings.
-It this is necessary, extra migrations steps need to be taken for the exsing bindings in the CF's Cloud Controller.
+`logLevel` will set the logging level. Accepted levels: "debug", "info", "error", and "fatal".
 
-The brokerGoSqlDriver and brokerMssqlConnection are settings that the broker uses to connect to the mssql instance. brokerGoSqlDriver can be odbc (recommanded https://code.google.com/p/odbc/) for mssql (experimental https://github.com/denisenkom/go-mssqldb). brokerMssqlConnection is a map that is 
-converted into a connection string (e.g. "server=localhost;port=1433") consumed by odbc or mssql go library.
-Exmaple for a local trusted brokerMssqlConnection with odbc driver:
+The `brokerGoSqlDriver` and `brokerMssqlConnection` are settings that the broker uses to connect to the mssql instance. `brokerGoSqlDriver` can be "odbc"" (recommanded https://code.google.com/p/odbc/) or "mssql" (experimental https://github.com/denisenkom/go-mssqldb). `brokerMssqlConnection` is a key-value json object that is 
+converted into a connection string (e.g. {"server":"localhost","port":1433} is converted to  "server=localhost;port=1433") consumed by odbc or mssql go library.
+Exmaple for a local trusted `brokerMssqlConnection` with odbc driver:
 	{
 		"server":   "localhost\\sqlexpress",
 		"database": "master",
 		"driver": 	"sql server",
 		"trusted_connection": "yes"
 	}
 
-listeningAddr and brokerCredentials are used for the brokers http server. The CF CloudController will use this setting to connect to the broker.
+`listeningAddr` and `brokerCredentials` are used for the brokers http server. The CF CloudController will use this setting to connect to the broker.
+
+`dbIdentifierPrefix` is a string that is appended at the begining of the instance ID for the SQL Server database name, and at the begining of the binding id for the SQL Server user name. This will allow operators to easily idetify the databases managed by a particular mssql broker. Do not change this value on a existing mssql broker with active instances.
 
-dbIdentifierPrefix appended at the begining of the instance ID for the SQL Server database name, and it is appended at the begining of the binding id for the SQL Server user name. This will allow an adim to easily idetify the databases managed by a particular mssql broker.
+`serviceCatalog` is a JSON object using the CF Service API catalog format and is sent to the Cloud Controller to identify the service name and plans, and provide a description to the user about the service. To add more mssql brokers to the same CF cluster will require the following changes: 
+ > unique "name" for the service
+ > unique "id" for the service
+ > unique "id" for the plan
 
-serviceCatalog JSON is sent to the Cloud Controller to identify the service name and plans, and provide additional description to the user.
+`grantDbOwnerForBindings` sets the role for the binding credentails. If it is `true` the binding credential will have db_owner role. If it is `false` it wil have the db_ddladmin role and all grants for the dbo schema in the instnace database. It is not recommanded to change this value on a existing mssql broker with active bindings. Warning: setting tis value to `true` is dagerous and will allow the users to create backups (i.e. leak disk resources), drop the database (broker needs extra error and orphan handling), drop/create other users (i.e. delete cf bindings).
 
 ## Building and running
 
 Setup you GOPATH env variable
 
+```sh
 go get github.com/tools/godep
 go get github.com/hpcloud/cf-mssql-broker
 
 cd $GOPATH/src/github.com/hpcloud/cf-mssql-broker # cd $env:GOPATH/src/github.com/hpcloud/cf-mssql-broker
 
 godep restore
 go build
-cf-mssql-broker -config=cf_mssql_broker_config.json
 
+# change the required values from the reference config file (cf_mssql_broker_config.json)
+cf-mssql-broker -config=cf_mssql_broker_config.json
+```
 
 ## Using the broker with Curl REST calls
 
 ### Provision Instance
 
+```sh
 curl http://username:password@localhost:3000/v2/service_instances/instance1 -d '{ "service_id":  "b6844738-382b-4a9e-9f80-2ff5049d512f", "plan_id":           "fb740fd7-2029-467a-9256-63ecd882f11c",  "organization_guid": "org-guid-here", "space_guid":        "space-guid-here" }' -X PUT -H "X-Broker-API-Version: 2.4" -H "Content-Type: application/json"
+```
 
 ### Bind Service Instance
 
+```sh
 curl http://username:password@localhost:3000/v2/service_instances/instance1/service_bindings/binding1 -d '{  "plan_id":        "plan-guid-here",  "service_id":     "service-guid-here",  "app_guid":       "app-guid-here"}' -X PUT -H "X-Broker-API-Version: 2.4" -H "Content-Type: application/json"
+```
 
 ### Unbind Service Instance
 
+```sh
 curl 'http://username:password@localhost:3000/v2/service_instances/instance1/service_bindings/binding1?service_id=service-id-here&plan_id=plan-id-here' -X DELETE -H "X-Broker-API-Version: 2.4"
+```
 
 ### Deprovision Instance
+
+```sh
 curl 'http://username:password@localhost:3000/v2/service_instances/instance1?service_id=b6844738-382b-4a9e-9f80-2ff5049d512f&plan_id=fb740fd7-2029-467a-9256-63ecd882f11c' -X DELETE -H "X-Broker-API-Version: 2.4"
+```
 
 ## Windows Service installation
 
@@ -120,5 +138,7 @@ nssm start cf-mssql-broker
 
 You need admin access to a Cloud Foundry deployment to add a new service broker.
 
+```sh
 cf create-service-broker mssql-broker1 username password http://192.168.1.10:3000
 cf enable-service-access mssql-dev
+```